Alegeți platformele explicate de documentația Rust
Stabiliți explicit platformele documentate pe docs.rs pentru interfețele bibliotecii și verificați separat dovezile portabilității ei în execuție.
De 
Paul. Limbaje și framework-uri
O bibliotecă poate oferi o interfață pe care documentația implicită nu o arată niciodată. Compilarea condiționată face ca platforma să influențeze conținutul văzut de cititor. Dacă utilizatorii depind de funcții specifice unei platforme, alegerea țintelor de documentare aparține condițiilor de publicare. Lăsată în seama serviciului de găzduire, această alegere face ca interfața vizibilă să depindă de o politică pe care autorul bibliotecii nu o controlează.
Promisiunea potrivită este restrânsă: documentația ar trebui să explice interfețele oferite pe platformele pentru care biblioteca declară suport. Generarea cu succes a documentației nu demonstrează că interfețele funcționează corect în execuție. Sunt dovezi de natură diferită. Combinarea lor într-o singură etichetă de portabilitate i-ar induce în eroare atât pe dezvoltatorii care aleg dependența, cât și pe cei care îi aprobă folosirea.
Lista celor cinci ținte are o dată
Anunțul docs.rs din 16 octombrie 2025 a înlocuit macOS pentru Intel cu Apple silicon și Linux pe 32 de biți cu Linux ARM64 în compilările implicite pentru documentație. Lista rezultată era x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc, aarch64-unknown-linux-gnu și i686-pc-windows-msvc. Autorii puteau cere explicit țintele anterioare.
Lista oferă context istoric. Anunțul din 4 aprilie 2026 prevedea compilarea doar pentru ținta implicită începând cu 1 mai 2026, pentru versiuni noi și recompilări. Ar fi riscant să citiți anunțul vechi drept o garanție actuală pentru cinci platforme. O politică explicită de documentare rezistă unei asemenea schimbări mai bine decât amintirea unei valori implicite.
La configurarea unei versiuni reale trebuie păstrată și o neconcordanță între surse. Referința pentru metadate consultată pentru articol afișează încă valoarea implicită de cinci ținte. Anunțul datat din 2026 descrie schimbarea ulterioară. Folosiți referința pentru configurare cu această rezervă și inspectați rezultatele versiunii concrete înainte de a afirma că s-a generat un anumit set de pagini. Articolul nu relatează un experiment de compilare.
Stabiliți pagina de intrare a cititorului
Configurația se află în secțiunea [package.metadata.docs.rs] din Cargo.toml. Cheia default-target alege ținta paginii de intrare în documentație; targets exprimă lista țintelor cerute. Numele contează fiindcă prima pagină deschisă de cititor și acoperirea completă sunt decizii înrudite, dar răspund unor întrebări diferite. O bibliotecă specifică unei platforme ar trebui să le ia deliberat pe amândouă.
Referința descrie targets = [] ca solicitare de compilare doar pentru ținta implicită și explică alegerea primei intrări din targets când default-target lipsește. Textul ei curent descrie și compilări suplimentare atunci când există o țintă implicită explicită. Anunțul ulterior spune că lista explicită targets se compilează exact cum este specificată. Pentru a evita dependența de această neconcordanță, includeți ținta paginii de intrare în lista explicită și verificați paginile generate pentru versiunea publicată.
Opțiunile funcționale cer o decizie separată. Aceeași referință prezintă features, all-features și no-default-features. Lista platformelor nu explică singură interfețele opționale. Alegeți combinația de opțiuni reprezentată de documentația publică și precizați domeniul ei lângă legătura către documentație. Altfel, cititorii pot descoperi abia la integrare că funcția dorită este documentată pentru o configurație diferită de a lor.
Verificați vizibilitatea înaintea portabilității
Începeți verificarea unei versiuni cu interfețele care diferă între platforme. Pentru fiecare platformă promisă, urmăriți dacă cititorul poate găsi API-ul aplicabil și îi poate înțelege condițiile. Deschideți legăturile așa cum ar face utilizatorul bibliotecii. Succesul unei sarcini de compilare într-un panou oferă mai puține informații decât verificarea interfeței promise în pagina platformei relevante.
Examinați apoi separat afirmația privind execuția. Generarea documentației nu poate demonstra semantica sistemului de fișiere, disponibilitatea bibliotecilor native sau interacțiunea corectă cu un serviciu al platformei. Acestea depind de bibliotecă și de folosirea ei. Alegeți verificări care exercită comportamentul promis, fără să le înlocuiți cu o pagină generată. Aceasta este o practică propusă pentru publicare, nu constatarea că o bibliotecă menționată aici ar fi eșuat la asemenea verificări.
Și nivelurile de suport trebuie interpretate cu grijă. Politica proiectului unui limbaj și promisiunea unei biblioteci privesc niveluri diferite. Anunțul docs.rs leagă schimbarea țintei Apple de nivelurile Rust; nu certifică astfel comportamentul fiecărei biblioteci pe Apple silicon. Autorul bibliotecii trebuie să definească interfața mai restrânsă și comportamentul pe care este pregătit să le întrețină.
O singură țintă poate fi suficientă
Cel mai puternic contraargument privește consumul de resurse. O bibliotecă ale cărei interfețe sunt identice pe platformele acceptate poate câștiga puțin din mai multe compilări de documentație. Anunțul din 2026 justifică reducerea prin lipsa obișnuită a codului dependent de țintă și prin resursele economisite. Obligarea tuturor bibliotecilor să reproducă lista veche ar crea muncă redundantă.
Recomandarea se aplică atunci când alegerea țintei schimbă informația necesară cititorului. O singură țintă de documentare poate fi rezonabilă pentru o interfață portabilă dacă declarația de suport are dovezi potrivite în altă parte. Nici cinci pagini generate nu stabilesc un suport mai larg dacă nimeni nu le verifică și nu întreține integrarea platformelor respective.
Păstrați politica suficient de scurtă pentru a fi folosită la publicare. Numiți ținta paginii de intrare, interfețele suplimentare care merită expuse și combinația de opțiuni prezentată. Consemnați ce s-a generat efectiv pentru versiunea verificată. Separați afirmația despre execuție și dovezile ei. Următorul responsabil va putea astfel recunoaște o schimbare relevantă a valorilor implicite ale serviciului.
Pentru dezvoltarea software la comandă, când integrarea depinde de o bibliotecă Rust, cereți documentație potrivită țintei aplicației înainte de a decide integrarea. Rezultatul util este o interfață vizibilă și o așteptare privind execuția susținută separat. Metadatele explicite fac alegerea documentației verificabilă chiar dacă serviciul de găzduire își schimbă din nou politica implicită.