Adding install, typos fixed

.gitlab-ci.yml

@@ -9,9 +9,19 @@ cache:
 before_script:
   - npm install gitbook-cli -g # install gitbook
   - gitbook fetch latest # fetch latest stable version
+  - gitbook install # add any requested plugins in book.json
   #- gitbook fetch pre # fetch latest pre-release version
   #- gitbook fetch 2.6.7 # fetch specific version
 
+test:
+  stage: test
+  script:
+    - gitbook build . public # build to public path
+  only:
+    - branches # this job will affect only the 'master' branch
+  except:
+    - master
+    
 # the 'pages' job will deploy and build your site to the 'public' path
 pages:
   stage: deploy
@@ -20,5 +30,7 @@ pages:
   artifacts:
     paths:
       - public
+    expire_in: 1 week
   only:
     - master # this job will affect only the 'master' branch
+

README.md

@@ -8,9 +8,9 @@ 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).
+Nor the horrible 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.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.
+It's clean, powerful, and elegant, so you can spend most of your time coding, not adding lines to an unreadable, unmaintainable Make (Or CMake 2) file.
 
 {% hint style='working' %}
 This document is a work in progress.
@@ -24,8 +24,8 @@ Do any of the following apply to you?
 
 * You want to avoid hard-coding paths
 * You need to build a package on more than one computer
-* You want to use CI (continious integration)
-* You need to support diffent OSs (maybe even just flavors of Unix)
+* You want to use CI (continuous integration)
+* You need to support different OSs (maybe even just flavors of Unix)
 * You want to support multiple compilers
 * You want to use an IDE, but maybe not all of the time
 * You want to describe how your program is structured logically, not flags and commands
@@ -33,18 +33,18 @@ Do any of the following apply to you?
 * You want to use tools, like Clang-Tidy, to help you code
 * You want to use a debugger
 
-If so, you'll benifit from a CMake-like build system.
+If so, you'll benefit from a CMake-like build system.
 
 ## Why must the answer be CMake?
 
-Build systems is a hot topic. Of course there are many options. But even a really good one, or one that re-uses a familar syntax, can't come close to CMake.
+Build systems is a hot topic. Of course there are many options. But even a really good one, or one that re-uses a familiar syntax, can't come close to CMake.
 Why?
 Support.
 Every IDE supports CMake (or CMake supports that IDE).
 More packages use CMake than any other system.
 So, if you use a library that is designed to be included in your code, you have a choice: Make your own build system, or use one of of the provided ones, and that will almost always include CMake.
 And that will quickly be the common denominator if you include multiple projects.
-And, if you need a library that's preinstalled, the chances of it having a find cmake script or config cmake script are excellent.
+And, if you need a library that's preinstalled, the chances of it having a find CMake script or config CMake script are excellent.
 
 
 ## Why use a Modern CMake?
@@ -64,7 +64,7 @@ Even though every version of CMake is insanely backward compatible, the 3 series
 And so, you'll find OS's like CentOS7 with GCC 4.8, with almost-complete C++14 support, and CMake 2.8, which came out before C++11.
 
 You really should *at least* use a version of CMake that came out after your compiler, since it needs to know compiler flags, etc, for that version.
-And, since CMake will dumb itself down to the minimium required version in your CMake file, installing a new CMake, even system wide, is pretty safe.
+And, since CMake will dumb itself down to the minimum required version in your CMake file, installing a new CMake, even system wide, is pretty safe.
 You should *at least* install it locally.
 It's easy (1-2 lines in many cases), and you'll find that 5 minutes of work will save you hundreds of lines and hours of CMakeLists.txt writing, and will be much easier to maintain in the long run.
 

SUMMARY.md

@@ -1,7 +1,7 @@
 # Summary
 
 * [An Introduction to Modern CMake](README.md)
-* [Installing CMake](chapters/install.md)
+* [Installing CMake](chapters/installing.md)
 * [Running CMake](chapters/running.md)
 
 ## Making a CMakeLists

chapters/basics.md

@@ -14,6 +14,11 @@ Let's mention a bit of CMake syntax. The function name is case insensitive, so t
 This line is special! [^2] The version of CMake will also dictate the policies, which define behavior changes. So, if you set `minimum_required` to `VERSION 2.8`, you'll get the wrong linking behavior on macOS, for example, even in the newest CMake versions. A list of policies and versions is [here](https://cmake.org/cmake/help/v3.9/manual/cmake-policies.7.html).
 
 
+{% hint style='info' %}
+If you really need to set to a low value here, you can use [`cmake_policy`] to conditinally increase the policy level or set a specific policy. Please at least do this for your macOS users!
+{% endhint %}
+
+
 ## Setting a project
 
 Now, every top-level CMake file will have the next line:
@@ -105,3 +110,5 @@ target_link_libraries(calc PUBLIC calclib)
 [^2]: You will sometimes see `FATAL_ERROR` here, that was needed to support nice failures when running this in CMake <2.6, which should not be a problem anymore.
 
 [^3]: The `::` syntax was originally intended for `INTERFACE IMPORTED` libraries, which were explicitly supposed to be libraries defined outside the current project. But, because of this, most of the `target_*` commands don't work on `IMPORTED` libraries, making them hard to set up yourself. So don't use the `IMPORTED` keyword for now, and use an `ALIAS` target instead. There's a project in the works to fix this limitation for CMake 3.11.
+
+[`cmake_policy`]: https://cmake.org/cmake/help/v3.0/command/cmake_policy.html

chapters/installing.md

@@ -0,0 +1,50 @@
+# Installing CMake
+
+> Your CMake version should be newer than your compiler. It should be newer than the libraries you are using (especially Boost). New versions work better for everyone.
+
+If you have a built in copy of CMake, it isn't special or customized for your system. You can easily install a new one instead, either on the system level or the user level. Feel free to instruct your users here if they complain about a CMake requirement being set too high. Especially if they want < 3.1 support. Maybe even if they want CMake < 3.8 support...
+
+## Official package
+
+You can [download CMake from KitWare][cmake-download]. This is how you'll probably get CMake if you are on Windows. It's not a bad way to get it on macOS either, but using `brew install cmake` is much nicer if you use [Homebrew](https://brew.sh) (and you should).
+
+On Linux, there are binaries provided, but you'll need to pick an install location. If you already use `~/.local` for user-space packages, the following single line command will get CMake for you [^1]:
+
+{% terminal %}
+~ $ wget -qO- "https://cmake.org/files/v3.9/cmake-3.9.4-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C ~/.local
+{% endterminal %}
+
+If you just want a local folder with CMake only:
+
+{% terminal %}
+~ $ mkdir -p cmake39 && wget -qO- "https://cmake.org/files/v3.9/cmake-3.9.4-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C cmake39
+~ $ export PATH=`pwd`/cmake39/bin:$PATH
+{% endterminal %}
+
+You'll obviously want to append to the PATH every time you start a new terminal, or add it to your `.bashrc` or to an [LMod] system.
+
+And, if you want a system install (I'm only brave enough to run this in Docker):
+
+You can also build CMake on any system, it's pretty easy, but binaries are faster.
+
+## Pip
+
+This is also provide as an official package, maintained by the authors of CMake at KitWare. It's a rather new method, and might fail on some systems (Alpine isn't supported last I checked, but that has CMake 3.8), but works really well when it works (like on Travis CI). If you have pip (Python's package installer), you can do:
+
+```bash
+pip install cmake
+```
+
+And as long as a binary exists for your system, you'll be up-and-running almost immediately. If a binary doesn't exist, it will try to use KitWare's `scikit-build` package to build, which currently can't be listed as a dependency in the packaging system, and might even require (an older) copy of CMake to build. So only use this system if binaries exist, which is most of the time.
+
+This has the benefit of respecting your current virtual environment, as well.
+
+{% hint style='info' %}
+Personally, on Linux, I put versions of CMake in folders, like `/opt/cmake39` or `~/opt/cmake39`, and then add them to [LMod]. See [`envmodule_setup`] for help setting up an LMod system on macOS or Linux. It's takes a bit to learn, but is a great way to manage package and compiler versions.
+{% endhint %}
+
+[^1]: If don't have a `.local` in your home directory, it's easy to start. Just make the folder, then add `export PATH="$HOME/.local/bin:$PATH"` to your `.bashrc` or `.bash_profile` or `.profile` file in your home directory. Now you can install any packages you build to `-DCMAKE_INSTALL_PREFIX=~/.local` instead of `/usr/local`!
+
+[cmake-download]: https://cmake.org/download/
+[LMod]: http://lmod.readthedocs.io/en/latest/
+[`envmodule_setup`]: https://github.com/CLIUtils/envmodule_setup

chapters/running.md

@@ -57,4 +57,5 @@ You can also build just a part of a build by specifying a target, such as the na
 These are common CMake options to most packages:
 
 * `-DCMAKE_BUILD_TYPE=` Pick from Release, RelWithDebInfo, Debug, or sometimes more.
-* `-DCMAKE_INSTALL_PREFIX=` The location to install to. System install on UNIX would often be `/usr/local` (the default), user directories are often `~/.local`, or you can pick a folder.
+* `-DCMAKE_INSTALL_PREFIX=` The location to install to. System install on UNIX would often be `/usr/local` (the default), user directories are often `~/.local`, or you can pick a folder.
+* `-D BUILD_SHARED_LIBS=` You can set this `ON` or `OFF` to control the default for shared libraries (the author can pick one vs. the other explicitly instead of using the default, though)