-
Notifications
You must be signed in to change notification settings - Fork 2.5k
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.
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
cmake build enhancements, mostly for windows, with some documentation #315
Open
jeking3
wants to merge
1
commit into
madler:master
Choose a base branch
from
jeking3:msvc-cmake-enhancements
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| # Building zlib with CMake # | ||
|
|
||
| ## Prerequisites ## | ||
|
|
||
| CMake version 2.4.4 or later is required. [Download](https://cmake.org/download/) and install the latest CMake (recommended). | ||
|
|
||
| ## Introduction ## | ||
|
|
||
| If you are not familiar with CMake, this project is a great way to learn how it works. Let's define a couple directories we'll refer to throughout the document: | ||
|
|
||
| - `BUILDDIR` is the directory where the build takes place | ||
| - `BUILDTYPE` is one of the CMake standard build types: `Debug`, `RelWithDebInfo`, or `Release`. | ||
| - `INSTDIR` is the directory where the build result is installed | ||
| - `SRCDIR` is the directory that contains the zlib project files | ||
|
|
||
| CMake takes cmake script files (typically called CMakeLists.txt) from `SRCDIR` and generates an entire platform-specific build environment in `BUILDDIR`. CMake supports output of many different build environments, such as make, ninja, and NMake to name a few. CMake also supports generation of IDE projects for Eclipse, Visual Studio, and others. | ||
|
|
||
| ## Invocation ## | ||
|
|
||
| Generating an out-of-tree build directory with CMake is trivial: | ||
|
|
||
| 1. Create the `BUILDDIR`. | ||
| 2. cd into `BUILDDIR`. | ||
| 3. cmake `SRCDIR` `-DCMAKE_INSTALL_PREFIX=INSTDIR` `<other-options>` | ||
|
|
||
| ## Options ## | ||
|
|
||
| Options are defined when you generate the build environment. Options are defined by passing them with a `-D` prefix on the cmake command line. Here are the options that matter most when building zlib: | ||
|
|
||
| | Option | Origin | Default | Meaning | | ||
| | :----- | -----: | ------: | :------ | | ||
| | `ASM686` | zlib | `OFF` | Build with an i686 assembly implementation | | ||
| | `AMD64` | zlib | `OFF` | Build with an x86_64 assembly implementation | | ||
| | `BUILD_SHARED_LIBS` | cmake | `ON` | Build a shared library | | ||
| | `BUILD_STATIC_AND_SHARED` | zlib | `ON` | Build both a shared and a static library* | | ||
| | `CMAKE_BUILD_TYPE` | cmake | `Debug` | Defines the build type at generation time** | | ||
| | `CMAKE_INSTALL_PREFIX` | cmake | depends | Build prefix for installation, platform specific| | ||
| | `SKIP_INSTALL_ALL` | zlib | `OFF` | Skip installation of everything | | ||
| | `SKIP_INSTALL_FILES` | zlib | `OFF` | Skip installation of manual pages and pkgconfig files | | ||
| | `SKIP_INSTALL_HEADERS` | zlib | `OFF` | Skip installation of headers | | ||
| | `SKIP_INSTALL_LIRARIES` | zlib | `OFF` | Skip installation of binaries, libraries, and symbol files | | ||
|
|
||
| \* The CMake build for zlib produces static and shared libraries in the same build by default. This behavior is not always optimal for building on every platform, therefore a CMake option called `BUILD_STATIC_AND_SHARED` was introduced to allow the caller to disable this combined build and honor the more commonly used `BUILD_SHARED_LIBS` CMake option instead. | ||
|
|
||
| \** `CMAKE_BUILD_TYPE` is only used on Unix. For Windows, the build type is defined at build time, not at generation time. | ||
|
|
||
| A default build without options will create a shared library, debug build, and attempt to install it into a system-wide visible location (`/usr/local` on Unix, and `C:\Program Files` on Windows). | ||
|
|
||
| ## Unix ## | ||
|
|
||
| Unix does not suffer from as many runtime library choices as Windows, and is therefore quite simple. Using a minimal set of options we end up with static and shared builds as output: | ||
|
|
||
| $ mkdir <BUILDDIR> | ||
| $ cd <BUILDDIR> | ||
| $ cmake <SRCDIR> -DCMAKE_INSTALL_PREFIX=<INSTDIR> -DCMAKE_BUILD_TYPE=<BUILDTYPE> | ||
| $ cmake --build . --target install | ||
|
|
||
| ### Generating Eclipse Projects ### | ||
|
|
||
| CMake has the ability to generate Eclipse projects. When invoking cmake in `BUILDDIR`, specify the generator: | ||
|
|
||
| $ cmake `<SRCDIR>` -G"Eclipse CDT4 - Unix Makefiles" | ||
|
|
||
| This will produce an Eclipse solution targeting `make` builds. A full list of generators can be obtained by running this command and scrolling to the end of the output: | ||
|
|
||
| cmake --help | ||
|
|
||
| ## Windows ## | ||
|
|
||
| Building on Windows, with the large number of library configuration options, is a little more complicated. For example one can build a statically-linked zlib that uses a dynamic runtime library, or one can build a statically-linked zlib that uses a static MSVC runtime library. The CMake install target will put only the files you need into `INSTDIR`. If the build contains debugging information, that will be included. Some examples for building on Windows are found below. | ||
|
|
||
| ### DLL (shared) with MSVCRT DLL ### | ||
|
|
||
| C:\BUILDDIR> cmake C:\SRCDIR -DCMAKE_INSTALL_PREFIX=<INSTDIR> -DBUILD_STATIC_AND_SHARED=OFF | ||
| C:\BUILDDIR> cmake --build . --target install --config <BUILDTYPE> | ||
|
|
||
| ### LIB (static) with MSVCRT LIB (statically linked runtime) ### | ||
|
|
||
| C:\BUILDDIR> cmake C:\SRCDIR -DCMAKE_INSTALL_PREFIX=<INSTDIR> -DBUILD_STATIC_AND_SHARED=OFF -DBUILD_SHARED_LIBS=OFF -DCMAKE_C_FLAGS_<BUILDTYPE>="/MT /Z7" | ||
| C:\BUILDDIR> cmake --build . --target install --config <BUILDTYPE> | ||
|
|
||
| Note the use of `CMAKE_C_FLAGS_<BUILDTYPE>` here, which is equivalent to using `CFLAGS` in a make build for a given `BUILDTYPE`. Options typically used here are: | ||
|
|
||
| - `/MT` to force a static release runtime link | ||
| - `/MTd` to force a static debug runtime link | ||
| - `/Z7` to put symbols in objects and libraries instead of a PDB file | ||
|
|
||
| ### Generating Visual Studio Projects ### | ||
|
|
||
| CMake has the ability to generate MSVC projects. When invoking cmake in `BUILDDIR`, specify the generator: | ||
|
|
||
| C:\TEMP\zlib-build> cmake C:\SRC\zlib -G"Visual Studio 15 2017 Win64" | ||
|
|
||
| This will produce a Visual Studio 2017 solution. A full list of generators can be obtained by running this command and scrolling to the end of the output: | ||
|
|
||
| cmake --help | ||
|
|
||
| ### Additional Resources ### | ||
|
|
||
| A full suite of example builds for Windows can be found in the `win32\cmake-matrix.bat` file. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| :: | ||
| :: Builds many different combinations of zlib on windows. | ||
| :: Provided as an example on how to build exactly what you want. | ||
| :: | ||
|
|
||
| @ECHO ON | ||
| SETLOCAL EnableDelayedExpansion | ||
|
|
||
| :: | ||
| :: Set these to your BUILDDIR, INSTDIR, and SRCDIR if needed - the | ||
| :: defaults should work fine if you run the batch script from win32. | ||
| :: The LOGFILE will receive directory listings from each build combo. | ||
| :: | ||
|
|
||
| SET ZLIB_BUILD=C:\temp\zlib\zlib-build | ||
| SET ZLIB_INSTALL=C:\temp\zlib\zlib-install | ||
| SET ZLIB_HOME=%CD%\.. | ||
| SET LOGFILE=C:\temp\zlib\zlib-matrix.log | ||
| @ECHO/ > %LOGFILE% | ||
|
|
||
| :: These are the stock builds for zlib (builds static and shared together) | ||
| CALL :BUILDONE Debug stock-debug | ||
| CALL :BUILDONE RelWithDebInfo stock-relwithdebinfo | ||
| CALL :BUILDONE Release stock-release | ||
|
|
||
| :: These are new build configurations targeting a single type and mode | ||
| CALL :BUILDONE Debug shared-debug "-DBUILD_STATIC_AND_SHARED=OFF" | ||
| CALL :BUILDONE RelWithDebInfo shared-relwithdebinfo "-DBUILD_STATIC_AND_SHARED=OFF" | ||
| CALL :BUILDONE Release shared-release "-DBUILD_STATIC_AND_SHARED=OFF" | ||
|
|
||
| :: For static debug library builds put the debug information in the library with /Z7 | ||
| CALL :BUILDONE Debug static-debug "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" "-DCMAKE_C_FLAGS_DEBUG=/Z7" | ||
| CALL :BUILDONE RelWithDebInfo static-relwithdebinfo "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" "-DCMAKE_C_FLAGS_RELWITHDEBINFO=/Z7" | ||
| CALL :BUILDONE Release static-release "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" | ||
|
|
||
| :: Static library with a static MSVC runtime: | ||
| CALL :BUILDONE Debug static-debug-static-rtl "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" "-DCMAKE_C_FLAGS_DEBUG=/MTd /Z7" | ||
| CALL :BUILDONE RelWithDebInfo static-relwithdebinfo-static-rtl "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" "-DCMAKE_C_FLAGS_RELWITHDEBINFO=/MT /Z7" | ||
| CALL :BUILDONE Release static-release-static-rtl "-DBUILD_STATIC_AND_SHARED=OFF" "-DBUILD_SHARED_LIBS=OFF" "-DCMAKE_C_FLAGS_RELEASE=/MT" | ||
|
|
||
| EXIT /B | ||
|
|
||
| :: \param[in] %1 Build Config | ||
| :: \param[in] %2 Build Name | ||
| :: \param[in] %3.. Build Options | ||
| :BUILDONE | ||
| IF EXIST %ZLIB_BUILD%\%2 (RMDIR /S /Q %ZLIB_BUILD%\%2) | ||
| IF EXIST %ZLIB_INSTALL%\%2 (RMDIR /S /Q %ZLIB_INSTALL%\%2) | ||
| MKDIR %ZLIB_BUILD%\%2 | ||
| CD %ZLIB_BUILD%\%2 | ||
| cmake %ZLIB_HOME% -DCMAKE_INSTALL_PREFIX=%ZLIB_INSTALL%\%2 %3 %4 %5 %6 %7 || EXIT /B | ||
| cmake --build . --target install --config %1 | ||
| @ECHO/ >> %LOGFILE% | ||
| @ECHO "-------------------------------------------------------------------------------" >> %LOGFILE% | ||
| @ECHO "-- %2" >> %LOGFILE% | ||
| @ECHO "-------------------------------------------------------------------------------" >> %LOGFILE% | ||
| DIR /S %ZLIB_INSTALL%\%2 >> %LOGFILE% |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#273 recommends a different approach - tagging so we don't lose track of it.