Skip to content

Commit

Permalink
Auto merge of #5600 - jrvidal:sys-packages, r=alexcrichton
Browse files Browse the repository at this point in the history
Clarify wording around `*-sys` packages

I am slightly confused by the wording about `*-sys` packages in the documentation. From what I could gather, Cargo does _not_ treat `foo-sys` in any special way, it's merely a convention _of the crates.io ecosystem_.

I've changed that, and also toned down the various "will do this" to "should do this", since nothing is actually _enforcing_ these conventions.

I am not a native speaker, so I might have read the whole thing wrong. 🤷‍♀️
  • Loading branch information
bors committed Jun 27, 2018
2 parents 5845464 + e255418 commit ce455cd
Showing 1 changed file with 5 additions and 5 deletions.
10 changes: 5 additions & 5 deletions src/doc/src/reference/build-scripts.md
Original file line number Diff line number Diff line change
Expand Up @@ -509,15 +509,15 @@ this space.

### `*-sys` Packages

To alleviate linking to system libraries, Cargo has a *convention* of package
naming and functionality. Any package named `foo-sys` will provide two major
To alleviate linking to system libraries, crates.io has a *convention* of package
naming and functionality. Any package named `foo-sys` should provide two major
pieces of functionality:

* The library crate will link to the native library `libfoo`. This will often
* The library crate should link to the native library `libfoo`. This will often
probe the current system for `libfoo` before resorting to building from
source.
* The library crate will provide **declarations** for functions in `libfoo`,
but it does **not** provide bindings or higher-level abstractions.
* The library crate should provide **declarations** for functions in `libfoo`,
but **not** bindings or higher-level abstractions.

The set of `*-sys` packages provides a common set of dependencies for linking
to native libraries. There are a number of benefits earned from having this
Expand Down

0 comments on commit ce455cd

Please sign in to comment.