Skip to content
Open
Show file tree
Hide file tree
Changes from 9 commits
Commits
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
56 changes: 30 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,19 @@
# osquery-toolchain

The script in this repository is used to build the LLVM/Clang toolchain which is used in the osquery project to create portable binaries of it.
The procedure to build such a toolchain has been based on the build-anywhere project: https://github.com/theopolis/build-anywhere

Following the main goals of the toolchain:

- Obtain a LLVM/Clang toolchain which is portable and which doesn't depend from libstdc++ or libgcc.
- The toolchain is compiled with a specific glibc version, so that it runs on a wide range of distributions.
- The toolchain lives in a sysroot folder which should be self sufficient.
- The toolchain should be able to produce binaries that are portable and run on libc >= 2.12.
- The toolchain should be able to produce binaries that are portable and run on libc >= 2.17 on x86_64 and libc >= 2.27 on aarch64.
To do so, the output binary should depend only on shared libraries which are deeply connected with the environment they run on,
typically libc, libdl, librt, libpthread.

The rough steps used to achieve the above goals:

- Use crosstool-ng to compile a stage0 GCC static toolchain, which might be newer than the one available in the system.
- Compile an older libz/zlib which is compatible with the old glibc.
- Link all GCC binaries into the sysroot created by crosstool-ng, so that the sysroot can be used for the next steps
Expand All @@ -21,50 +24,48 @@ The rough steps used to achieve the above goals:
- Use the stage1 Clang to compile a stage1 libunwind (static only)
- Use the stage1 Clang, libunwind, libc++/c++abi, compiler-rt builtins, to build a final/full toolchain

The version of crosstool-ng used is 1.24.0
The version of the GCC compiler built by crosstool-ng is 8.3.0
The version of the libc library built by crosstool-ng is 2.12.2
The version of LLVM/Clang built by the script is 11.0.0
The version of the zlib library built by the script is 1.2.11
The version of crosstool-ng used is 1.28.0
The version of the GCC compiler built by crosstool-ng is 13.4.0
The version of the libc library built by crosstool-ng is 2.17 (x86_64) / 2.27 (aarch64)
The version of LLVM/Clang built by the script is 18.1.8
The version of the zlib library built by the script is 1.3.1
The version of elfutils built by the script is 0.192
The version of libbpf built by the script is 1.5.0
The version of bpftool built by the script is 7.5.0

Among other, the toolchain LLVM/Clang includes the clang static analyzer, scan-build, clang-format, clang-tidy.
Among others, the toolchain LLVM/Clang includes the clang static analyzer, scan-build, clang-format, clang-tidy.

# How to build
Using a recent distribution with GCC 8 is suggested to reduce the possible crashes and issues that may happen when compiling
the portable GCC toolchain.
For the instructions we will use Ubuntu 18.04.

For the instructions we will use Ubuntu 22.04.

## Prerequisites

```
sudo apt install g++-8 gcc-8 automake autoconf gettext bison flex unzip help2man libtool-bin libncurses-dev make ninja-build patch txinfo gawk wget git texinfo xz-utils python
```
Then use `update-alternatives` to tell the system that the version of GCC/G++ and CPP is the default we would like to use:
```
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 20
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 20
sudo update-alternatives --install /usr/bin/cpp cpp /usr/bin/cpp-8 20
```
Download and install CMake 3.17.5
```
wget https://github.com/Kitware/CMake/releases/download/v3.17.5/cmake-3.17.5-Linux-x86_64.tar.gz
sudo tar xvf cmake-3.17.5-Linux-x86_64.tar.gz -C /usr/local --strip 1
sudo apt install -y g++ gcc automake autoconf gettext bison flex unzip help2man libtool-bin libncurses-dev make ninja-build patch txinfo gawk wget git texinfo xz-utils python3 python3-setuptools bzip2 cmake pkg-config
```

## Customize the configuration

The default configuration is ready to go, though if customization is needed, there are two files that can be modified: config and crosstool-ng-config.
- *config* contains global configuration values like, versions of llvm, zlib, how many parallel jobs to use, which build system to use and such.
- *crosstool-ng-config* contains the configuration that is feed into the crosstool-ng tool, which compiles the portable GCC.
It controls the GCC version built, libc and kernel headers version to build everything.
This is config normally generated by another tool that crosstool-ng provides, but the config can be manually modified after being generated.

- _config_ contains global configuration values like, versions of llvm, zlib, how many parallel jobs to use, which build system to use and such.
- _crosstool-ng-config_ contains the configuration that is feed into the crosstool-ng tool, which compiles the portable GCC.
It controls the GCC version built, libc and kernel headers version to build everything.
This is config normally generated by another tool that crosstool-ng provides, but the config can be manually modified after being generated.

## Build

The script has to be run as a normal user and accepts one argument, which is the folder where the various stages and the final toolchain will be built:

```
./build.sh /opt/osquery-toolchain
```

This should output the sysroot under `/opt/osquery-toolchain/final` and the LLVM toolchain will be under `/opt/osquery-toolchain/final/sysroot/usr`

## Redistributing and usage

1. Enter inside the **final** folder within the destination path
2. Rename the **sysroot** folder to **osquery-toolchain**
3. Compress the folder with the following command: `tar -pcvJf osquery-toolchain-<VERSION>.tar.xz osquery-toolchain`
Expand All @@ -79,16 +80,19 @@ Sometimes explicitly adding `-ldl` and/or `-lrt` is needed, depending on what fu
The only other flag that's needed is `--sysroot=<sysroot path>`, so that the toolchain searches what it needs in the correct path.

## Troubleshooting

If the compilation stops at any point in time, just relaunching the script should restart it.
The script doesn't delete anything when it restarts the build, so if you want to start clean from some substep, you need to do that manually.

So for more advanced troubleshooting, following the build example in general we have:

- `/opt/osquery-toolchain/stage0`: here lives crosstool-ng source code, build, zlib source code, build and GCC/G++ toolchain compiled by crosstool-ng. The GCC/G++ toolchain folder is also copied on the next stages
- `/opt/osquery-toolchain/stage1`: here lives the intermediate LLVM/Clang toolchain, together with a copy of the previous step GCC/G++ toolchain and it's used to build the final toolchain
- `/opt/osquery-toolchain/final`: here lives the final sysroot containing only the LLVM/Clang toolchain we want to use
- `/opt/osquery-toolchain/llvm`: here lives the source code for the LLVM/Clang and the various build folders for the LLVM build substeps

The script decides it has to build one of the stages if it doesn't find a specific file in one of the install folders (stage0, stage1, final).

- For crosstool-ng is `/opt/osquery-toolchain/stage0/crosstool-ng/ct-ng`.
- For GCC is `/opt/osquery-toolchain/stage0/x86_64-osquery-linux-gnu/bin/x86_64-osquery-linux-gnu-gcc`
- For zlib is `/opt/osquery-toolchain/stage0/x86_64-osquery-linux-gnu/x86_64-osquery-linux-gnu/usr/lib/libz.a`
Expand Down
Loading