diff --git a/01-basic/E-installing/CMakeLists.txt b/01-basic/E-installing/CMakeLists.txt new file mode 100644 index 0000000..35d41d4 --- /dev/null +++ b/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) diff --git a/01-basic/E-installing/README.adoc b/01-basic/E-installing/README.adoc new file mode 100644 index 0000000..c73f93b --- /dev/null +++ b/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 +``` diff --git a/01-basic/E-installing/README.md b/01-basic/E-installing/README.md deleted file mode 100644 index e69de29..0000000 diff --git a/01-basic/E-installing/cmake-examples.conf b/01-basic/E-installing/cmake-examples.conf new file mode 100644 index 0000000..d530261 --- /dev/null +++ b/01-basic/E-installing/cmake-examples.conf @@ -0,0 +1 @@ +# Sample configuration file that could be installed diff --git a/01-basic/E-installing/inc/Hello.h b/01-basic/E-installing/inc/Hello.h new file mode 100644 index 0000000..f838400 --- /dev/null +++ b/01-basic/E-installing/inc/Hello.h @@ -0,0 +1,10 @@ +#ifndef __HELLO_H__ +#define __HELLO_H__ + +class Hello +{ +public: + void print(); +}; + +#endif diff --git a/01-basic/E-installing/src/Hello.cpp b/01-basic/E-installing/src/Hello.cpp new file mode 100644 index 0000000..75c152d --- /dev/null +++ b/01-basic/E-installing/src/Hello.cpp @@ -0,0 +1,8 @@ +#include + +#include "Hello.h" + +void Hello::print() +{ + std::cout << "Hello Install!" << std::endl; +} diff --git a/01-basic/E-installing/src/main.cpp b/01-basic/E-installing/src/main.cpp new file mode 100644 index 0000000..62a1520 --- /dev/null +++ b/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; +} \ No newline at end of file