doc: document generating bindings with prebuilt libs2n #4872
Conversation
bindings/rust/README.md
Outdated
| @@ -20,6 +20,20 @@ Generating rust bindings can be accomplished by running the `generate.sh` script | |||
| $ ./bindings/rust/generate.sh | |||
| ``` | |||
|
|
|||
| Alternatively, rust bindings can be generated using pre-built libs2n by first compiling libs2n, and then running the `generate.sh` script: | |||
There was a problem hiding this comment.
I think we should be writing this from the perspective of external consumers, who wouldn't be able to run generate.sh. They'd just be pulling the generated s2n-tls-sys from crates.io.
So it's probably a little bit more useful to include a workflow oriented around "how do I call cargo build and use my own libs2n?", and skip the .generate.sh steps.
I think it would also be nice to be a bit more verbose about the process.
E.g.
- you do this be setting environment variables
- the environment variables point to ...
- the final artifact will then ...
There was a problem hiding this comment.
I rewrote the doc from the perspective of crates consumer with more details.
I believe this documentation is also valuable for direct crates consumers, so I added the same information in the readme for s2n-tls-sys crates (assuming this is the readme that is shown on creates page when published). This way, crates consumers are aware of this option when looking from crates.io, and they are also able to find this option at bindings/rust/README even if they are not aware of s2n-tls-sys crate
- document from the perspective of crates consumer - add the same information on crates' readme
| 2. cd into your rust project and set environment variables to libs2n library sources. | ||
|
|
||
| This tells the bindings to link to pre-built libs2n when running the build script for s2n-tls-sys |
There was a problem hiding this comment.
Let's include the raw definitions, because I think your example includes some assumptions which might not actually match customer environments.
E.g. call out that S2N_TLS_LIB_DIR points to the folder containing the libs2n.a artifact that you would like s2n-tls-sys to link against.
Also, maybe let's call out whether something is different with static vs dynamic libs?
There was a problem hiding this comment.
Added explanation on what each vars are for.
maybe let's call out whether something is different with static vs dynamic libs?
I understand static lib bakes the code to executable at build time and dynamic lib requires the linked libraries to be available at runtime. Is there something else we want to call out within the context of this bindings generation?
- add new header - raw definitions for export vars - mention default built steps
bindings/rust/s2n-tls-sys/README.md
Outdated
| ``` | ||
|
|
||
| `S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. |
There was a problem hiding this comment.
| `S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`lins2n.so` artifact that you would like s2n-tls-sys to link against. | |
| `S2N_TLS_LIB_DIR` points to the folder containing `libs2n.a`/`libs2n.so` artifact that you would like s2n-tls-sys to link against. |
|
|
||
| 1. Uses the system C compiler to build `libs2n.a` | ||
| 2. Links the built `libs2n.a` to the Rust bindings | ||
| 3. Links against `aws-lc` through the `aws-lc-rs` crate |
There was a problem hiding this comment.
Nit: I'd move this above the bring your own libs2n heading, because it it generally useful information.
- typo fix - move build process info up a section
Resolved issues:
This is one of the ORR action items to improve documentations on generating rust bindings:
Description of changes:
Documented an alternative way to generate bindings using pre-built libs2n, and provided an example code snippet for it. Added this to both bindings/rust/README and bindings/rust/s2n-tls-sys/README
Call-outs:
Testing:
Ran the documented commands locally and confirmed it triggers build process with prebuilt libs2n. The way I confirmed this is:
cargo add s2n-tls-sys.cargo runwhich printed out the message added in step 1By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.