From 47aa740c74b42c24485c762e7e0203db452464ac Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 16 Dec 2022 11:09:16 +1100 Subject: [PATCH] Improve the README files Improve the secp256k1 readme by: - Use a top level markdown header (level 1) - Add a link to the SECG's website (www.secg.org) - Add a link for `secp256k1` to bitcoin.it explaining the curve Improve the secp256k1-sys readme by: - Mirror secp256k1 readme badges, heading, docs link - Basic cleanup - Use 100 column width - Use backticks - Use capitals --- README.md | 21 ++++++++++----- secp256k1-sys/README.md | 57 +++++++++++++++++++++++++---------------- 2 files changed, 50 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 6023eb4..7200207 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,21 @@ -[![Build Status](https://travis-ci.org/rust-bitcoin/rust-secp256k1.png?branch=master)](https://travis-ci.org/rust-bitcoin/rust-secp256k1) +
+

Rust Secp256k1

-[Full documentation](https://docs.rs/secp256k1/) +

+ Crate Info + CC0 1.0 Universal Licensed + CI Status + API Docs + Rustc Version 1.48.0+ +

+
-## rust-secp256k1 +`rust-secp256k1` is a wrapper around [libsecp256k1](https://github.com/bitcoin-core/secp256k1), a C +library implementing various cryptographic functions using the [SECG](https://www.secg.org/) curve +[secp256k1](https://en.bitcoin.it/wiki/Secp256k1). + +This library: -`rust-secp256k1` is a wrapper around [libsecp256k1](https://github.com/bitcoin-core/secp256k1), -a C library by Pieter Wuille for producing ECDSA signatures using the SECG curve -`secp256k1`. This library * exposes type-safe Rust bindings for all `libsecp256k1` functions * implements key generation * implements deterministic nonce generation via RFC6979 diff --git a/secp256k1-sys/README.md b/secp256k1-sys/README.md index 5928b6c..3305e2d 100644 --- a/secp256k1-sys/README.md +++ b/secp256k1-sys/README.md @@ -1,38 +1,51 @@ -secp256k1-sys -============= +
+

Rust secp256k1-sys

+

+ Crate Info + CC0 1.0 Universal Licensed + API Docs + Rustc Version 1.48.0+ +

+
-This crate provides Rust definitions for the FFI structures and methods. - +Provides low-level bindings to the C FFI exposed by [libsecp256k1](https://github.com/bitcoin-core/secp256k1). ## Vendoring -The default build process is to build using the vendored libsecp256k1 sources in -the depend folder. These sources are prefixed with a special -rust-secp256k1-sys-specific prefix `rustsecp256k1_v1_2_3_`. +The default build process is to build using the vendored `libsecp256k1` sources in the `depend` +directory. These sources are prefixed with a special rust-secp256k1-sys-specific prefix +`rustsecp256k1_v1_2_3_`. This prefix ensures that no symbol collision can happen: -- when a Rust project has two different versions of rust-secp256k1 in its - depepdency tree, or -- when rust-secp256k1 is used for building a static library in a context where - existing libsecp256k1 symbols are already linked. -To update the vendored sources, use the `vendor-libsecp.sh` script: +- When a Rust project has two different versions of `rust-secp256k1` in its depepdency tree, or +- When `rust-secp256k1` is used for building a static library in a context where existing + `libsecp256k1` symbols are already linked. -``` -$ ./vendor-libsecp.sh -``` - -Where `` is the git revision of libsecp256k1 to checkout. If you do not -specify a revision, the script will simply clone the repo and use whatever -revision the default branch is pointing to. +To update the vendored sources, use the `vendor-libsecp.sh` script: `./vendor-libsecp.sh ` +- Where `` is the git revision of `libsecp256k1` to checkout. If you do not specify a revision, + the script will simply clone the repo and use whatever revision the default branch is pointing to. ## Linking to external symbols -If you want to compile this library without using the bundled symbols (which may -be required for integration into other build systems), you can do so by adding -`--cfg=rust_secp_no_symbol_renaming'` to your `RUSTFLAGS` variable. +**Danger: doing this incorrectly may have catastrophic consequences!** + +This is mainly intended for applications consisting of various programming languages that intend to +link the same library to save space, or bundles of multiple binaries coming from the same source. Do +not use this to link to a random secp256k1 library you found in your OS! If you are packaging +software that depends on `rust-secp256k1`, using this flag to link to another package, make sure you +stay within the binary compatibility guarantees of that package. For example, in Debian if you need +`libsecp256k1 1.2.3`, make sure your package requires a version strictly`>= 1.2.3 << 1.2.4`. Note +also that unless you're packaging the library for an official repository you should prefix your +package and the library with a string specific to you. E.g. if you have a set of packages called +`my-awesome-packages` you should package `libsecp256k1` as `libmy-awesome-packages-secp256k1` and +depend on that library/package name from your application. + +If you want to compile this library without using the bundled symbols (which may be required for +integration into other build systems), you can do so by adding `--cfg=rust_secp_no_symbol_renaming'` +to your `RUSTFLAGS` variable. ## Minimum Supported Rust Version