|
1 | | -secp256k1-sys |
2 | | -============= |
| 1 | +<div align="center"> |
| 2 | + <h1>Rust secp256k1-sys</h1> |
3 | 3 |
|
| 4 | + <p> |
| 5 | + <a href="https://crates.io/crates/secp256k1-sys"><img alt="Crate Info" src="https://img.shields.io/crates/v/secp256k1-sys.svg"/></a> |
| 6 | + <a href="https://github.com/rust-bitcoin/rust-secp256k1/blob/master/LICENSE"><img alt="CC0 1.0 Universal Licensed" src="https://img.shields.io/badge/license-CC0--1.0-blue.svg"/></a> |
| 7 | + <a href="https://docs.rs/secp256k1"><img alt="API Docs" src="https://img.shields.io/badge/docs.rs-secp256k1-green"/></a> |
| 8 | + <a href="https://blog.rust-lang.org/2020/02/27/Rust-1.48.0.html"><img alt="Rustc Version 1.48.0+" src="https://img.shields.io/badge/rustc-1.48.0%2B-lightgrey.svg"/></a> |
| 9 | + </p> |
| 10 | +</div> |
4 | 11 |
|
5 | | -This crate provides Rust definitions for the FFI structures and methods. |
6 | | - |
| 12 | +Provides low-level bindings to the C FFI exposed by [libsecp256k1](https://github.com/bitcoin-core/secp256k1). |
7 | 13 |
|
8 | 14 | ## Vendoring |
9 | 15 |
|
10 | | -The default build process is to build using the vendored libsecp256k1 sources in |
11 | | -the depend folder. These sources are prefixed with a special |
12 | | -rust-secp256k1-sys-specific prefix `rustsecp256k1_v1_2_3_`. |
| 16 | +The default build process is to build using the vendored `libsecp256k1` sources in the `depend` |
| 17 | +directory. These sources are prefixed with a special rust-secp256k1-sys-specific prefix |
| 18 | +`rustsecp256k1_v1_2_3_`. |
13 | 19 |
|
14 | 20 | This prefix ensures that no symbol collision can happen: |
15 | | -- when a Rust project has two different versions of rust-secp256k1 in its |
16 | | - depepdency tree, or |
17 | | -- when rust-secp256k1 is used for building a static library in a context where |
18 | | - existing libsecp256k1 symbols are already linked. |
19 | | - |
20 | | -To update the vendored sources, use the `vendor-libsecp.sh` script: |
21 | 21 |
|
22 | | -``` |
23 | | -$ ./vendor-libsecp.sh <rev> |
24 | | -``` |
| 22 | +- When a Rust project has two different versions of `rust-secp256k1` in its depepdency tree, or |
| 23 | +- When `rust-secp256k1` is used for building a static library in a context where existing |
| 24 | + `libsecp256k1` symbols are already linked. |
25 | 25 |
|
26 | | -Where `<rev>` is the git revision of libsecp256k1 to checkout. If you do not |
27 | | -specify a revision, the script will simply clone the repo and use whatever |
28 | | -revision the default branch is pointing to. |
| 26 | +To update the vendored sources, use the `vendor-libsecp.sh` script: `./vendor-libsecp.sh <rev>` |
29 | 27 |
|
| 28 | +- Where `<rev>` is the git revision of `libsecp256k1` to checkout. If you do not specify a revision, |
| 29 | + the script will simply clone the repo and use whatever revision the default branch is pointing to. |
30 | 30 |
|
31 | 31 | ## Linking to external symbols |
32 | 32 |
|
33 | | -If you want to compile this library without using the bundled symbols (which may |
34 | | -be required for integration into other build systems), you can do so by adding |
35 | | -`--cfg=rust_secp_no_symbol_renaming'` to your `RUSTFLAGS` variable. |
| 33 | +**Danger: doing this incorrectly may have catastrophic consequences!** |
| 34 | + |
| 35 | +This is mainly intended for applications consisting of various programming languages that intend to |
| 36 | +link the same library to save space, or bundles of multiple binaries coming from the same source. Do |
| 37 | +not use this to link to a random secp256k1 library you found in your OS! If you are packaging |
| 38 | +software that depends on `rust-secp256k1`, using this flag to link to another package, make sure you |
| 39 | +stay within the binary compatibility guarantees of that package. For example, in Debian if you need |
| 40 | +`libsecp256k1 1.2.3`, make sure your package requires a version strictly`>= 1.2.3 << 1.2.4`. Note |
| 41 | +also that unless you're packaging the library for an official repository you should prefix your |
| 42 | +package and the library with a string specific to you. E.g. if you have a set of packages called |
| 43 | +`my-awesome-packages` you should package `libsecp256k1` as `libmy-awesome-packages-secp256k1` and |
| 44 | +depend on that library/package name from your application. |
| 45 | + |
| 46 | +If you want to compile this library without using the bundled symbols (which may be required for |
| 47 | +integration into other build systems), you can do so by adding `--cfg=rust_secp_no_symbol_renaming'` |
| 48 | +to your `RUSTFLAGS` variable. |
36 | 49 |
|
37 | 50 | ## Minimum Supported Rust Version |
38 | 51 |
|
|
0 commit comments