diff --git a/.gitignore b/.gitignore index 09ea21b..6f925ef 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ -_book/ +/_book/ +/node_modules/ +/book.pdf +/book.mobi +/book.epub diff --git a/README.md b/README.md index ab542dd..e692db5 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,21 @@ -![Build Status](https://gitlab.com/CLIUtils/modern-cmake/badges/master/build.svg) +# An Introduction to Modern CMake ---- -An introduction to Modern CMake practices - ---- People love to hate build systems. -Just watch the talks from CppCon17. +Just watch the talks from CppCon17 to see examples of developers making the state of build systems the brunt of jokes. This raises the question: Why? Certainly there are no shortage of problems when building. But I think that, in 2017, we have a very good solution to quite a few of those problems. It's CMake. Not CMake 2.8 though; that was released before C++11 even existed! Nor the horible examples out there for CMake (even those posted on KitWare's own tutorials list). -I'm talking about Modern CMake. CMake 3.1+, maybe even CMake 3.9! +I'm talking about Modern CMake. CMake 3.1+, maybe even CMake 3.8+! It's clean, powerful, and elegant, so you can spend most of your time coding, not addding lines to an unreadable, unmaintainable Make (Or CMake 2) file. +{% hint style='working' %} +This document is a work in progress. +{% endhint %} + In short, here are the most likely questions in your mind if you are considering Modern CMake: ## Why do I need a good build system? @@ -70,4 +70,3 @@ It's easy (1-2 lines in many cases), and you'll find that 5 minutes of work will This book tries to solve the problem of the poor examples and best practices that you'll find proliferating the web. -This document is a work in progress. diff --git a/SUMMARY.md b/SUMMARY.md index 5fe5884..341fe58 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,9 +1,11 @@ # Summary -* [Introduction](README.md) -## Making a CMakeLists +* [An Introduction to Modern CMake](README.md) * [Installing CMake](chapters/install.md) * [Running CMake](chapters/running.md) + +## Making a CMakeLists + * [Introduction to the basics](chapters/basics.md) * [Adding features (like C++11)](chapters/features.md) * [How to structure your project](chapters/structure.md) @@ -15,7 +17,8 @@ * [IDEs](chapters/IDEs.md) * [Debugging](chapters/IDEs.md) -## Specific use cases +## Specific packages + * [CUDA](specifics/CUDA.md) * [OpenMP](specifics/OpenMP.md) * [Boost](specifics/Boost.md) diff --git a/book.json b/book.json new file mode 100644 index 0000000..3b47cc8 --- /dev/null +++ b/book.json @@ -0,0 +1,6 @@ +{ + "title": "Modern CMake", + "description": "A guide to writing simple, powerful, and clean CMake 3.1+ builds.", + "author": "Henry Schreiner", + "plugins": ["hints","terminal@https://github.com/henryiii/gitbook-plugin-terminal.git"] +} diff --git a/chapters/running.md b/chapters/running.md index 41b53a5..809dc69 100644 --- a/chapters/running.md +++ b/chapters/running.md @@ -7,12 +7,12 @@ Unless otherwise noted, you should always make a build directory and build from Here's the CMake Build Procedure (TM): -```bash -mkdir build -cd build -cmake .. -make -``` +{% terminal %} +~/package $ mkdir build +~/package $ cd build +~/package/build $ cmake .. +~/package/build $ make +{% endterminal %} You can replace the make line with `cmake --build .` if you'd like, and it will call `make` or whatever build tool you are using. You can follow it by `make install` or `cmake --build . --target install` if you want to install it. @@ -20,18 +20,19 @@ You can replace the make line with `cmake --build .` if you'd like, and it will Selecting a compiler must be done on the first run in an empty directory. It's not CMake syntax per-say, but you might not be familiar with it. To pick Clang: -```bash -CC=clang CXX=clang++ cmake .. -``` +{% terminal %} +~/package/build $ CC=clang CXX=clang++ cmake .. +{% endterminal %} That sets the environment variables in bash for CC and CXX, and CMake will respect those variables. This sets it just for that one line, but that's the only time you'll need those; afterwards CMake continues to use the paths it deduces from those values. ## Picking a generator You can build with a variety of tools; `make` is usually the default. To see all the tools CMake knows about on your system, run -``` -cmake --help -``` + +{% terminal %} +~/package/build $ cmake --help +{% endterminal %} And you can pick a tool with `-G"My Tool"` (quotes only needed if spaces are in the tool name). You should pick a tool on your first CMake call in a directory, just like the compiler. Feel free to have several build directories, like `build/` and `buildXcode`. @@ -43,7 +44,9 @@ You set options in CMake with `-D`. You can see a list of options with `-L`, or Again, not really CMake, but if you are using a command line build tool like `make`, you can get verbose builds: -VERBOSE=1 make +{% terminal %} +~/package/build $ VERBOSE=1 make +{% endterminal %} You can actually write `make VERBOSE=1`, and make will also do the right thing, though that's a feature of `make` and not the command line in general.