Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Edits to BUILD.md #4155

Closed
wants to merge 9 commits into from
+85 −49
Closed

docs: Edits to BUILD.md #4155

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b6ea51c
Docs: Template-based edits to BUILD.md
kagarmoe Aug 15, 2023
46a55d0
support tables
kagarmoe Aug 16, 2023
02aa7f2
typo fix
kagarmoe Aug 18, 2023
61a9ca3
it's spelled avail-ABLE
kagarmoe Aug 18, 2023
97c2989
Apply suggestions from code review
kagarmoe Sep 25, 2023
326d80a
support matrix v2
kagarmoe Sep 26, 2023
35f3fd7
Remove support matrix
kagarmoe Sep 29, 2023
fc99867
AWS-LC options
kagarmoe Sep 29, 2023
11846ea
Feedback; Need RAM spec
kagarmoe Oct 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 85 additions & 49 deletions docs/BUILD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,36 @@
# Building s2n-tls

s2n-tls can be built as follows:
To use s2n-tls, you must build the library from the source and then include it in your program.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Could "from source" be used here? It reads a bit better to me.

Suggested change
To use s2n-tls, you must build the library from the source and then include it in your program.
To use s2n-tls, you must build the library from source and then include it in your program.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't feel correct to say that you must build s2n-tls from source to use it. We don't know how customers are consuming s2n-tls-- they could already have a binary. I don't think this wording change is an improvement.


## Requirements

s2n-tls supports and tests on **x86** and **arm** architectures.

s2n-tls does not currently support building on Windows. See https://github.com/aws/s2n-tls/issues/497 for more information.

### System requirements

* 20GB RAM available, recommended.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, this requirement/recommendation sounds extreme. Building s2n-tls should require such a small amount of RAM that I'm not sure it makes sense to specify a requirement for it.

#4155 (comment)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've compiled it on a RaspberryPi with 4GB RAM; considering we have IoT uses, one could argue this is relevant.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Giving system requirements is a normal piece of information. It a good thing to to have for everbody, but it is especially important for edge devices. I need a size for the recommended available RAM.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would maybe go with 4GB then, since that's probably the least amount of RAM that we know has been tested.

Copy link
Contributor

@lrstewart lrstewart Oct 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're going to document requirements, we shouldn't be guessing at those requirements. They need to be accurate. And are we intending this as build requirements or runtime requirements?


### Software requirements

Building s2n-tls requires:

1. GCC or Clang
1. CMake
1. Libcrypto, such as AWS-LC or OpenSSL
1. Platform-specific build tools
goatgoose marked this conversation as resolved.
Show resolved Hide resolved

## Building s2n-tls from the source
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same nit:

Suggested change
## Building s2n-tls from the source
## Building s2n-tls from source


Clone s2n-tls and change directories into the repo:

```bash
git clone https://github.com/aws/s2n-tls.git
cd s2n-tls
kagarmoe marked this conversation as resolved.
Show resolved Hide resolved
```

Follow the instructions for your platform:

<details open>
<summary>Ubuntu</summary>
Expand All @@ -14,13 +44,14 @@ sudo apt install cmake
sudo apt install libssl-dev

# build s2n-tls
cmake . -Bbuild \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=./s2n-tls-install
cmake . -B build \
-D CMAKE_BUILD_TYPE=Release \
-D CMAKE_INSTALL_PREFIX=./s2n-tls-install
Comment on lines +48 to +49
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've never seen cmake -D with a space like that. It somehow looks very wrong lol. I'd prefer we follow the more common cmake conventions and not put a space after -D.

cmake --build build -j $(nproc)
CTEST_PARALLEL_LEVEL=$(nproc) ctest --test-dir build
cmake --install build
```

</details>

<details>
Expand All @@ -34,10 +65,10 @@ brew install cmake
brew install openssl@3

# build s2n-tls
cmake . -Bbuild \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_PREFIX_PATH=$(dirname $(dirname $(brew list openssl@3|grep libcrypto.dylib))) \
-DCMAKE_INSTALL_PREFIX=./s2n-tls-install
cmake . -B build \
-D CMAKE_BUILD_TYPE=Release \
-D CMAKE_PREFIX_PATH=$(dirname $(dirname $(brew list openssl@3|grep libcrypto.dylib))) \
-D CMAKE_INSTALL_PREFIX=./s2n-tls-install
cmake --build build -j $(sysctl -n hw.ncpu)
CTEST_PARALLEL_LEVEL=$(sysctl -n hw.ncpu) ctest --test-dir build
cmake --install build
Expand All @@ -56,29 +87,29 @@ sudo yum install cmake3
sudo yum install openssl-devel

# build s2n-tls
cmake . -Bbuild \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=./s2n-tls-install \
-DCMAKE_EXE_LINKER_FLAGS="-lcrypto -lz"
cmake . -B build \
-D CMAKE_BUILD_TYPE=Release \
-D CMAKE_INSTALL_PREFIX=./s2n-tls-install \
-D CMAKE_EXE_LINKER_FLAGS="-lcrypto -lz"
cmake --build build -j $(nproc)
CTEST_PARALLEL_LEVEL=$(nproc) ctest --test-dir build
cmake --install build
```
</details>

Note that we currently do not support building on Windows. See https://github.com/aws/s2n-tls/issues/497 for more information.
kagarmoe marked this conversation as resolved.
Show resolved Hide resolved
</details>

See the [s2n-tls usage guide](USAGE-GUIDE.md#consuming-s2n-tls-via-cmake) for instructions on how to include s2n-tls in your CMake project.
> See the [s2n-tls usage guide](USAGE-GUIDE.md#consuming-s2n-tls-via-cmake) for instructions on how to include s2n-tls in your CMake project.

Comment on lines +101 to 102
Copy link
Contributor

@lrstewart lrstewart Oct 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Why is this a block quote now?

## Configuring the s2n-tls build

s2n-tls can be configured with the following CMake options. Each option can be set by passing a `-D<option>=<value>` flag to CMake.
- [**`CMAKE_BUILD_TYPE`**](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html): Sets the build type. Some of the possible build types are as follows:
- `Release`: Produce an optimized s2n-tls library artifact with no debug info. This option should be used when building s2n-tls for use in production.
- `Debug`: Produce an unoptimized library artifact with debug info. This option can be used when developing for or with s2n-tls. The debug symbols produced with this build can be used with GDB and other utilities to help with debugging.
- [**`CMAKE_INSTALL_PREFIX`**](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html): Specifies where the s2n-tls library artifacts are placed when installing s2n-tls.
- [**`CMAKE_PREFIX_PATH`**](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html): Specifies install locations used by CMake to search for library dependencies. This option can be used to link s2n-tls to a specific libcrypto. See the [Building with a specific libcrypto](#building-with-a-specific-libcrypto) section for more information on building with different libcryptos.
- [**`BUILD_SHARED_LIBS`**](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html): Specifies whether a static or shared s2n-tls library artifact will be produced during the build. Defaults to `OFF`, building a static library. If set to `ON`, a shared library will be produced instead.
The following CMake options are useful for configuring s2n-tls builds. Each option can be set by passing a `-D <option>=<value>` flag to CMake.

- [**`CMAKE_BUILD_TYPE`**](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html): Sets the build type.
- `Release`: Produce an optimized s2n-tls library artifact without debug info. Use this option to build s2n-tls for use in production.
Comment on lines +107 to +108
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's clear that your nested bullets are possible values

- `Debug`: Produce an unoptimized library artifact with debug info. Use this option for developing with s2n-tls. The debug symbols produced with this build work with GDB and other utilities for debugging.
- [**`CMAKE_INSTALL_PREFIX`**](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html): Specifies the install directory for the s2n-tls library artifacts. Default: `/usr/local`
- [**`CMAKE_PREFIX_PATH`**](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html): Specifies the directories that CMake will search for library dependencies. Use this option to link s2n-tls to a specific libcrypto. See [Building with a specific libcrypto](#building-with-a-specific-libcrypto) for more information.
- [**`BUILD_SHARED_LIBS`**](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html): Specifies the type of s2n-tls library artifact produced by the build, either static or shared. Default: `OFF`, for a static library. Set to `ON`, for a shared library.

The entire list of s2n-tls CMake options can be viewed with the following command:

Expand All @@ -88,7 +119,15 @@ cmake . -LH

## Building with a specific libcrypto

s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be linked to s2n-tls when building. The following libcrypto libraries are currently supported:
s2n-tls requires a supported libcrypto library. A supported libcrypto must be linked to s2n-tls when building.

By default, s2n-tls searches for a system libcrypto to link with when building.
Override the default behavior by setting the `CMAKE_PREFIX_PATH` option to the install directory of a supported libcrypto.

### Supported libcrypto

s2n-tls supports the following libcrypto libraries:

- [AWS-LC](https://github.com/aws/aws-lc)
- [OpenSSL](https://www.openssl.org/) (versions 1.0.2 - 3.0)
kagarmoe marked this conversation as resolved.
Show resolved Hide resolved
- ChaChaPoly is not supported before Openssl-1.1.1.
Expand All @@ -98,16 +137,12 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l
- OCSP features are not supported with BoringSSL.
- [LibreSSL](https://www.libressl.org/)

By default, s2n-tls will attempt to find a system libcrypto to link with when building. However, this search can be overridden to any of the above libcryptos by specifying the install directory with the `CMAKE_PREFIX_PATH` flag.

For help building a desired libcrypto on your platform, please consult the project's build documentation.
For help building a desired libcrypto on your platform, consult the build documentation for that libcrypto.

### AWS-LC

[AWS-LC](https://github.com/aws/aws-lc) is the recommended libcrypto to use with s2n-tls due to increased performance and security. See the [AWS-LC build documentation](https://github.com/aws/aws-lc/blob/main/BUILDING.md) for information on building AWS-LC.

The `CMAKE_INSTALL_PREFIX` option can be provided when building AWS-LC to specify where AWS-LC will be installed. The install path for AWS-LC should be provided when building s2n-tls, via the `CMAKE_PREFIX_PATH` option. This will ensure that s2n-tls is able to find the AWS-LC library artifact to link with.

Comment on lines -109 to -110
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I'm guessing you removed this because aws-lc should own its own build instructions. But since we're specifically calling out aws-lc as our recommended option, maybe we want to keep these quick / easy access instructions on building the two libraries together.

## Other build methods

### Ninja build system
Expand All @@ -123,7 +158,7 @@ sudo apt update
sudo apt install ninja-build

# build s2n-tls with ninja
cmake . -Bbuild -GNinja \
cmake . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=./s2n-tls-install
ninja -C build -j $(nproc)
Expand All @@ -134,7 +169,7 @@ ninja -C build install

### Traditional Makefile

CMake is the preferred build system for s2n-tls since it includes updated build features and supports the most platforms. However, building s2n-tls with a traditional Makefile is also supported on some platforms. With make, the desired libcrypto install path must be set with the `LIBCRYPTO_ROOT` environment variable.
CMake is the preferred build system for s2n-tls because it includes updated build features and supports many platforms. However, building s2n-tls with a traditional Makefile is also supported on some platforms. To use make, set the `LIBCRYPTO_ROOT` environment variable to the libcrypto install path.

<details open>
<summary>Ubuntu</summary>
Expand All @@ -155,24 +190,7 @@ configure; build

For more information on installing Nix and using Nix with s2n-tls, see the [s2n-tls Nix documentation](../nix/README.md).

## mlock() and system limits

Internally s2n-tls uses mlock() to prevent memory from being swapped to disk. The
s2n-tls build tests may fail in some environments where the default limit on locked
memory is too low. To check this limit, run:

```bash
ulimit -l
```

to raise the limit, consult the documentation for your platform.

### Disabling mlock()

To disable s2n-tls's mlock behavior, run your application with the `S2N_DONT_MLOCK` environment variable set to 1.
s2n-tls also reads this for unit tests. Try setting this environment variable before running the unit tests if you're having mlock failures.

## Cross Compiling for 32 Bit Platforms
### Cross compiling for 32-bit platforms

There is an example toolchain for 32 bit cross-compiling in [`cmake/toolchains/32-bit.toolchain`](../cmake/toolchains/32-bit.toolchain).

Expand All @@ -196,8 +214,26 @@ sudo apt install libssl-dev:i386
rm -rf build

# build with the toolchain
cmake . -Bbuild -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/32-bit.toolchain
cmake . -B build -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/32-bit.toolchain
cmake --build ./build -j $(nproc)
CTEST_PARALLEL_LEVEL=$(nproc) ctest --test-dir build
```
</details>

## Troubleshooting

### Memory management and system limits (mlock failures)

s2n-tls uses `mlock()` to prevent memory from being swapped to disk. The
s2n-tls build tests may fail in some environments if the default limit on locked
memory is too low. To check this limit, run:

```bash
ulimit -l
```

Consult the documentation for your platform for instructions on raising the default limit on locked memory.

### Deactivate mlock()

Deactivate s2n-tls's `mlock` behavior by setting the `S2N_DONT_MLOCK` environment variable set to 1. s2n-tls also reads this for unit tests. If you're having mlock failures, try setting `S2N_DONT_MLOCK=1`.
Loading