Add the install example

01-basic/E-installing/CMakeLists.txt

@@ -0,0 +1,54 @@
+cmake_minimum_required(VERSION 2.6)
+
+project(cmake_examples_install)
+
+include_directories(
+    ${PROJECT_SOURCE_DIR}/inc
+    )
+
+############################################################
+# Create a library
+############################################################
+
+# Source files to be used in the library
+set(library_SOURCES
+    src/Hello.cpp
+)
+
+#Generate the shared library from the library sources
+add_library(cmake_examples_inst SHARED ${library_SOURCES})
+
+############################################################
+# Create an executable
+############################################################
+
+# Source fles for the binary
+set(binary_SOURCES
+    src/main.cpp
+)
+
+# Add an executable with the above sources
+add_executable(cmake_examples_inst_bin ${binary_SOURCES})
+
+# link the new hello_library target with the hello_binary target
+target_link_libraries( cmake_examples_inst_bin
+    cmake_examples_inst
+)
+
+############################################################
+# Install
+############################################################
+
+# Binaries
+install (TARGETS cmake_examples_inst_bin
+    DESTINATION bin)
+
+# Library
+# Note: may not work on windows
+install (TARGETS cmake_examples_inst
+    LIBRARY DESTINATION lib)
+
+
+# Config
+install (FILES cmake-examples.conf
+    DESTINATION etc)

01-basic/E-installing/README.adoc

@@ -0,0 +1,234 @@
+= Installing
+
+:toc:
+:toc-placement!:
+
+toc::[]
+
+
+[[intro]]
+Introduction
+------------
+
+This example shows how to generate a `make install` target to install files and
+binaries on your system. This is based on the previous shared library example.
+
+The files in this tutorial are below:
+
+```
+$ tree
+.
+├── cmake-examples.conf
+├── CMakeLists.txt
+├── inc
+│   └── Hello.h
+├── README.adoc
+└── src
+    ├── Hello.cpp
+    └── main.cpp
+```
+
+  * CMakeLists.txt - Contains the CMake commands you wish to run
+  * cmake-examples.conf - An example configuration file
+  * inc/Hello.h - The header file to include
+  * src/Hello.cpp - A source file to compile
+  * src/main.cpp - The source file with main
+
+[[concepts]]
+Concepts
+~~~~~~~~
+
+[[install]]
+Installing
+^^^^^^^^^^
+
+CMake offers the ability to add a `make install` target to allow a user to
+install binaries, libraries and other files. The base install location is controlled
+by the variable +CMAKE_INSTALL_PREFIX+ which can be set using ccmake or by calling
+cmake with `cmake .. -DCMAKE_INSTALL_PREFIX=/install/location`
+
+The files that are installed are controlled by the https://cmake.org/cmake/help/v3.0/command/install.html[+install()+] function.
+
+[source,cmake]
+----
+install (TARGETS cmake_examples_inst_bin
+    DESTINATION bin)
+----
+
+Install the binary generated from the target cmake_examples_inst_bin target to
+the destination +${CMAKE_INSTALL_PREFIX}/bin+
+
+[source,cmake]
+----
+install (TARGETS cmake_examples_inst
+    LIBRARY DESTINATION lib)
+----
+
+Install the shared library generated from the target cmake_examples_inst target to
+the destination +${CMAKE_INSTALL_PREFIX}/lib+
+
+[NOTE]
+====
+This may not work on windows. On platforms that have DLL targets you
+may need to add the following
+
+[source,cmake]
+----
+install (TARGETS cmake_examples_inst
+    LIBRARY DESTINATION lib
+    RUNTIME DESTINATION bin)
+----
+====
+
+[source,cmake]
+----
+install (FILES cmake-examples.conf
+    DESTINATION etc)
+----
+
+Install a configuration file to the destination +${CMAKE_INSTALL_PREFIX}/etc+
+
+After `make install` has been run, CMake generated an install_manifest.txt file
+which includes details on all installed files.
+
+[NOTE]
+====
+If you run the `make install` command as root, the install_manifest.txt file will
+be owned by root.
+====
+
+[[building-the-example]]
+Building the Example
+~~~~~~~~~~~~~~~~~~~~
+
+[source,bash]
+----
+$ mkdir build
+
+$ cd build/
+
+$ cmake ..
+-- The C compiler identification is GNU 4.8.4
+-- The CXX compiler identification is GNU 4.8.4
+-- Check for working C compiler: /usr/bin/cc
+-- Check for working C compiler: /usr/bin/cc -- works
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Check for working CXX compiler: /usr/bin/c++
+-- Check for working CXX compiler: /usr/bin/c++ -- works
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/matrim/workspace/cmake-examples/01-basic/E-installing/build
+
+$ make
+Scanning dependencies of target cmake_examples_inst
+[ 50%] Building CXX object CMakeFiles/cmake_examples_inst.dir/src/Hello.cpp.o
+Linking CXX shared library libcmake_examples_inst.so
+[ 50%] Built target cmake_examples_inst
+Scanning dependencies of target cmake_examples_inst_bin
+[100%] Building CXX object CMakeFiles/cmake_examples_inst_bin.dir/src/main.cpp.o
+Linking CXX executable cmake_examples_inst_bin
+[100%] Built target cmake_examples_inst_bin
+
+$ sudo make install
+[sudo] password for matrim:
+[ 50%] Built target cmake_examples_inst
+[100%] Built target cmake_examples_inst_bin
+Install the project...
+-- Install configuration: ""
+-- Installing: /usr/local/bin/cmake_examples_inst_bin
+-- Removed runtime path from "/usr/local/bin/cmake_examples_inst_bin"
+-- Installing: /usr/local/lib/libcmake_examples_inst.so
+-- Installing: /usr/local/etc/cmake-examples.conf
+
+$ cat install_manifest.txt
+/usr/local/bin/cmake_examples_inst_bin
+/usr/local/lib/libcmake_examples_inst.so
+/usr/local/etc/cmake-examples.conf
+
+$ ls /usr/local/bin/
+cmake_examples_inst_bin
+
+$ ls /usr/local/lib
+libcmake_examples_inst.so
+
+$ ls /usr/local/etc/
+cmake-examples.conf
+
+$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib cmake_examples_inst_bin
+Hello Install!
+----
+
+[NOTE]
+====
+If `/usr/local/lib` is not in your library path you may need to add it to the
+path before running the binary.
+====
+
+[[extra-notes]]
+Extra Notes
+~~~~~~~~~~~
+
+[[default-location]]
+Overriding the default install location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As mentioned the default install location is set from the +CMAKE_INSTALL_PERFIX+,
+which defaults to `/usr/local/`
+
+If you want to change this default location for all users you can add the
+following code to your top level CMakeLists.txt before adding any binaries or
+libraries.
+
+[source,cmake]
+----
+if( CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT )
+  message(STATUS "Setting default CMAKE_INSTALL_PREFIX path to ${CMAKE_BINARY_DIR}/install")
+  set(CMAKE_INSTALL_PREFIX "${CMAKE_BINARY_DIR}/install" CACHE STRING "The path to use for make install" FORCE)
+endif()
+----
+
+This example sets the default install location to under your build directory.
+
+[[destdir]]
+DESTDIR
+^^^^^^^
+
+If you wish to stage your install to confirm that all files are included the
+`make install` target supports the DESTDIR argument.
+
+```
+make install DESTDIR=/tmp/stage
+```
+
+This will create the install path `${DESTDIR}/${CMAKE_INSTALL_PREFIX}` for all
+your installation files. In this example, it would install all files under the
+path `/tmp/stage/usr/local`
+
+```
+$ tree /tmp/stage
+/tmp/stage
+└── usr
+    └── local
+        ├── bin
+        │   └── cmake_examples_inst_bin
+        ├── etc
+        │   └── cmake-examples.conf
+        └── lib
+            └── libcmake_examples_inst.so
+```
+
+[[uninstall]]
+Uninstall
+^^^^^^^^^
+
+By default CMake does not add a `make uninstall` target. For details on how to generate
+an uninstall target see this https://cmake.org/Wiki/CMake_FAQ#Can_I_do_.22make_uninstall.22_with_CMake.3F[FAQ]
+
+For an easy way to remove the files from this example, you can use:
+
+```
+sudo xargs rm < install_manifest.txt
+```

01-basic/E-installing/cmake-examples.conf

@@ -0,0 +1 @@
+# Sample configuration file that could be installed

01-basic/E-installing/inc/Hello.h

@@ -0,0 +1,10 @@
+#ifndef __HELLO_H__
+#define __HELLO_H__
+
+class Hello
+{
+public:
+    void print();
+};
+
+#endif

01-basic/E-installing/src/Hello.cpp

@@ -0,0 +1,8 @@
+#include <iostream>
+
+#include "Hello.h"
+
+void Hello::print()
+{
+    std::cout << "Hello Install!" << std::endl;
+}

01-basic/E-installing/src/main.cpp

@@ -0,0 +1,8 @@
+#include "Hello.h"
+
+int main(int argc, char *argv[])
+{
+    Hello hi;
+    hi.print();
+    return 0;
+}