281 lines
8 KiB
Markdown
281 lines
8 KiB
Markdown
# Compiling bzip2
|
|
|
|
The following build systems are available for Bzip2:
|
|
|
|
* [Meson]: This is our preferred build system for Unix-like systems.
|
|
* [CMake]: Build tool for Unix and Windows.
|
|
|
|
Meson works for Unix-like OSes and Windows; nmake is only for Windows.
|
|
|
|
[Meson]: https://mesonbuild.com
|
|
[CMake]: https://cmake.org
|
|
|
|
> _Important note when compiling for Linux_:
|
|
>
|
|
> The SONAME for libbz2 for version 1.0 was: `libbz2.so.1.0`
|
|
> Some distros patched it to libbz2.so.1 to be supported by libtool.
|
|
> Others did not.
|
|
>
|
|
> We had to make a choice when switching from Makefiles -> CMake + Meson.
|
|
> So, the SONAME for libbz2 for version 1.1 is now: `libbz2.so.1`
|
|
>
|
|
> Distros that need it to be ABI compatible with the old SONAME may either:
|
|
> 1. Use CMake for the build with the option `-D USE_OLD_SONAME=ON`.
|
|
> This will build an extra copy of the library with the old SONAME.
|
|
>
|
|
> 2. Use `patchelf --set-soname` after the build to change the SONAME and
|
|
> install an extra symlink manually: `libbz2.so.1.0 -> libbz2.so.1.0.9`
|
|
>
|
|
> You can check the SONAME with: `objdump -p libbz2.so.1.0.9 | grep SONAME`
|
|
|
|
## Using Meson
|
|
|
|
Meson provides a [large number of built-in options](https://mesonbuild.com/Builtin-options.html)
|
|
to control compilation. A few important ones are listed below:
|
|
|
|
- -Ddefault_library=[static|shared|both], defaults to shared, if you wish to
|
|
statically link libbz2 into the binaries set this to `static`
|
|
- --backend : defaults to ninja, use `vs` if you want to use msbuild
|
|
- --unity : This enables a unity build (sometimes called a jumbo build), makes a single build faster but rebuilds slower
|
|
- -Dbuildtype=[debug|debugoptmized|release|minsize|plain] : Controls default optimization/debug generation args,
|
|
defaults to `debug`, use `plain` if you wish to pass your own cflags.
|
|
|
|
Meson recognizes environment variables like `$CFLAGS` and `$CC`.
|
|
It is recommended that you do not use `$CFLAGS`, and instead use `-Dc_args` and
|
|
`-DC_link_args`, as Meson will remember these even if you need to reconfigure
|
|
from scratch (such as when you update Meson), it will not remember `$CFLAGS`.
|
|
|
|
Meson will never change compilers once configured, so `$CC` is perfectly safe.
|
|
|
|
### Unix-like (Linux, *BSD, Cygwin, macOS)
|
|
|
|
You will need:
|
|
- Python 3.6 or newer (for 3.5 for Meson and 3.6 for the tests)
|
|
- Python's 'pytest' module, for running the tests.
|
|
- meson (Version 0.56 or newer)
|
|
- ninja
|
|
- pkg-config
|
|
- A C compiler such as GCC or Clang
|
|
|
|
Some linux distros package managers refer to ninja as ninja-build, fedora
|
|
and debian/ubuntu both do this. Your OS probably provides Meson, although
|
|
it may be too old, in that case you can use python3's pip to install Meson:
|
|
|
|
```sh
|
|
sudo pip3 install meson
|
|
```
|
|
or, for a user local install:
|
|
```sh
|
|
pip3 install --user meson
|
|
```
|
|
|
|
Once you have installed the dependencies, the following should work
|
|
to use the standard Meson configuration, a `builddir` for
|
|
compilation, and a `/usr` prefix for installation:
|
|
|
|
```sh
|
|
meson --prefix /usr builddir/
|
|
ninja -C builddir
|
|
meson test -C builddir --print-errorlogs
|
|
[sudo] ninja -C builddir install
|
|
```
|
|
|
|
You can use `meson configure builddir` to check configuration options.
|
|
Currently bzip only has one project specific option, which is to force the
|
|
generation of documentation on or off.
|
|
|
|
Ninja acepts many of the same arguments as make, although it will
|
|
automatically detect the number of CPU cores available and use an appropriate
|
|
number of threads.
|
|
|
|
### Windows
|
|
|
|
You will need:
|
|
- Python 3.6 or newer
|
|
- Meson
|
|
- Visual Studio 2015+ (Community edition is fine)
|
|
|
|
You can install Meson with Python's pip package manager:
|
|
```cmd
|
|
python -m pip install meson
|
|
```
|
|
or you can [download pre-bundled installers of meson directly from meson's github](https://github.com/mesonbuild/meson/releases).
|
|
|
|
Either should work fine for the purposes of building Bzip2.
|
|
|
|
You will also need pkg-config. There are many sources of pkg-config, I
|
|
recommend installing from Chocolatey because it's easy. Chocolatey can also
|
|
provide Ninja, though Ninja is not required on Windows if you want to use
|
|
msbuild.
|
|
|
|
If you want to use MSVC or a compatible compiler launch the associated
|
|
environment cmd to run Meson from; the environments required to make those
|
|
compilers work is quite complex otherwise.
|
|
|
|
Once you have all of that installed you can invoke Meson to configure the
|
|
build. By default Meson will generate a Ninja backend. If you would prefer to
|
|
use msbuild, pass the backend flag `--backend=vs`. MSVC (and compatible
|
|
compilers like clang-cl and ICL) work with Ninja as well.
|
|
|
|
```cmd
|
|
meson $builddir
|
|
ninja -C $builddir
|
|
meson test -C builddir --print-errorlogs
|
|
```
|
|
|
|
or:
|
|
```cmd
|
|
meson $builddir --backend=vs
|
|
cd $builddir
|
|
msbuild bzip2.sln /m
|
|
```
|
|
|
|
## Using CMake
|
|
|
|
### Requirements
|
|
|
|
For Linux/Unix:
|
|
- Python 3.6 or newer (for 3.5 for Meson and 3.6 for the tests)
|
|
- CMake (Version 3.12 or newer)
|
|
- A C compiler such as GCC or Clang
|
|
|
|
For Windows:
|
|
- Python 3.6 or newer
|
|
- CMake
|
|
- Visual Studio 2015+ (Community edition is fine)
|
|
|
|
### Build instructions for Unix & Windows (CMake)
|
|
|
|
Bzip2 can be compiled with the [CMake] build system.
|
|
You can use these commands to build Bzip2 in a certain `build` directory.
|
|
|
|
#### Basic Release build
|
|
|
|
Linux/Unix:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DCMAKE_BUILD_TYPE="Release"
|
|
cmake --build .
|
|
ctest -V
|
|
```
|
|
|
|
Windows:
|
|
```ps1
|
|
mkdir build && cd build
|
|
cmake ..
|
|
cmake --build . --config Release
|
|
ctest -C Release -V
|
|
```
|
|
|
|
#### Basic Debug build
|
|
|
|
Linux/Unix:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DCMAKE_BUILD_TYPE="Debug"
|
|
cmake --build .
|
|
ctest -V
|
|
```
|
|
|
|
Windows:
|
|
```ps1
|
|
mkdir build && cd build
|
|
cmake ..
|
|
cmake --build . --config Debug
|
|
ctest -C Release -V
|
|
```
|
|
|
|
#### Build and install to a specific install location (prefix)
|
|
|
|
Linux/Unix:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DCMAKE_BUILD_TYPE="Release" -DCMAKE_INSTALL_PREFIX=install
|
|
cmake --build .
|
|
ctest -V
|
|
cmake --build . --target install
|
|
```
|
|
|
|
Windows:
|
|
```ps1
|
|
mkdir build && cd build
|
|
cmake .. -DCMAKE_INSTALL_PREFIX=install
|
|
cmake --build . --config Release
|
|
ctest -C Release -V
|
|
cmake --build . --config Release --target install
|
|
```
|
|
|
|
#### Other CMake Options
|
|
|
|
`ENABLE_EXAMPLES`: Default: `OFF`
|
|
Enabling this option will also build the "dlltest" example executable. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_EXAMPLES=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_DOCS`: Default: `OFF`
|
|
Enabling this option will generate extra documentation. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_DOCS=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_APP`: Default: `ON`
|
|
Disabling this option will prevent building `bzip` or any of the other programs
|
|
that come with `bzip2`. It will also disable the tests. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_APP=OFF
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_LIB_ONLY`: Default: `OFF`
|
|
Enabling this option is similar to disabling `ENABLE_APP`. Only libbz2 will be
|
|
compiled. It will also disable the tests. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_LIB_ONLY=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_STATIC_LIB`: Default: `OFF`
|
|
Enabling this option will build a static version of libbz2.
|
|
If `ENABLE_SHARED_LIB` is also enabled, the apps will link with the shared one.
|
|
E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_STATIC_LIB=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_SHARED_LIB`: Default: `ON`
|
|
Disabling this option will not build a shared version of libbz2. You must enable
|
|
`ENABLE_STATIC_LIB` if you disable `ENABLE_SHARED_LIB`. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_SHARED_LIB=OFF -DENABLE_STATIC_LIB=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`USE_OLD_SONAME`: Default: `OFF`
|
|
Enabling this option will build an extra copy of the shared library that uses
|
|
the old SONAME. This option is made available for some linux distributions that
|
|
still distribute libbz2 with the old SONAME. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DUSE_OLD_SONAME=ON
|
|
cmake --build .
|
|
```
|
|
|
|
`ENABLE_STATIC_LIB_IS_PIC`: Default: `ON`
|
|
Disabling this option will make it so that building the static library will not
|
|
use the '-fPIC'/'-fPIE' compiler options. You may need to disable this option if
|
|
your compiler cannot generate position-independent code for your platform. E.g.:
|
|
```sh
|
|
mkdir build && cd build
|
|
cmake .. -DENABLE_STATIC_LIB_IS_PIC=OFF
|
|
cmake --build .
|
|
```
|