File: installation.md

package info (click to toggle)
foonathan-memory 0.7-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 1,748 kB
  • sloc: cpp: 12,014; xml: 139; sh: 49; makefile: 22
file content (85 lines) | stat: -rw-r--r-- 5,107 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# Installation

This library can either be used [CMake]'s `add_subdirectory()` command or installed globally.

## Requirements

* git
* CMake version 3.1 or higher
* GCC 4.9 or higher, or clang 3.5 or higher or Visual Studio 14 or higher

## As subdirectory of your project

### 1. Fetching

It is recommended to setup a [git submodule] inside your project.
Simply run:

1. `git submodule add https://github.com/foonathan/memory ext/memory`. This will clone the latest commit into a local directory `ext/memory` and registers it as a submodule.
2. `git submodule update --init --recursive`. This will fetches the latest commits from all submodules `memory` itself is using.

If you later want to update your local copy to the latest version, simply run: `git submodule update --recursive --remote`.

### 2. CMake Setup

I am assuming that there is a local copy of the library source files under the path `ext/memory`.

In your `CMakeLists.txt` place a call to `add_subdirectory(ext/memory)`.
This will make all targets of `memory` available inside your CMakeLists.txt.
If you want to configure the library, add `set(option value CACHE INTERNAL "" FORCE)` before the `add_subdirectory()` command.
See [options] for a list of all configuration options and CMake variables.

Now the targets is available and to use the library in your application, call to `target_link_libraries(target foonathan_memory)`.
This will also setups the include search path of the compiler, as well as other required flags.

### 3. Code Usage

In your code you simply need to include the appropriate headers and you are good to got.
Everything is under the subdirectory `foonathan/memory` so write `#include <foonathan/memory/heap_allocator.hpp>` to use the [heap_allocator].

## Installing the library

Download or clone the source for the library version you want to install.
You can build the library inside the source directory, it will not be needed after the installation.

For each build type, run `cmake -DCMAKE_BUILD_TYPE="buildtype" -DFOONATHAN_MEMORY_BUILD_EXAMPLES=OFF -DFOONATHAN_MEMORY_BUILD_TESTS=OFF .` with possible other [options] to configure, then simply `cmake --build . -- install` to build and install the library.
This will install the header files under `${CMAKE_INSTALL_PREFIX}/include/foonathan_memory-${major}.${minor}`, the tools under `${CMAKE_INSTALL_PREFIX}/bin` and the build artifacts under `${CMAKE_INSTALL_PREFIX}/lib/foonathan_memory-${major}.${minor}`. 
By default, `${CMAKE_INSTALL_PREFIX}` is `/usr/local` under UNIX and `C:/Program Files` under Windows,
installation may require `sudo`/administrative privileges.

It is recommended that you install the library for the `Debug`, `RelWithDebInfo` and `Release` build types.
Each build type allows different CMake configurations and compiler flags, you can also create your own.

## Using an installed library (CMake)

After you've installed the library, all you need to call is `find_package(foonathan_memory major.minor REQUIRED)` to find it.
This will look for a library installation of a compatible version and the same build type as your project,
i.e. if you compile under build type `Debug`, it will also match the `Debug` library.
This *should* work without your help, otherwise it will tell you what to do.

A `0.x` version requires an exact match in the call to `find_package()`, otherwise a library with same major version and a higher minor version is also compatible.
If you want only exact version matches add the `EXACT` flag to `find_package()`.

If a right library version/configuration cannot be found, this is an error due to the `REQUIRED`.
If this is not what you want, leave it out and do conditionals based on the CMake variable `foonathan_memory_FOUND`.
In the source code, all targets linking to the library have the macro `FOONATHAN_MEMORY` defined automatically,
as `FOONATHAN_MEMORY_VERSION_MAJOR/MINOR`.
Use conditional compilation with them.

After that you can link to the library by calling `target_link_libraries(your_target PUBLIC foonathan_memory)`.
This setups everything needed.

Then simply include the headers, everything is under the subdirectory `foonathan/memory` so write `#include <foonathan/memory/heap_allocator.hpp>` to use the [heap_allocator].

## Using an installed library (other buildsystems)

To use the library with other build-systems, add `${CMAKE_INSTALL_PREFIX}/include/foonathan_memory-${major}.${minor}` and `${CMAKE_INSTALL_PREFIX}/lib/foonathan_memory-${major}.${minor}/${CMAKE_BUILD_TYPE}` to your include directories path.
Link to the library file in `${CMAKE_INSTALL_PREFIX}/lib/foonathan_memory-${major}.${minor}/${CMAKE_BUILD_TYPE}` and enable the right C++ standard for your configuration.

You should also globally define the `FOONATHAN_MEMORY` macro as `1` and the `FOONATHAN_MEMORY_VERSION_MAJOR/MINOR` macros as the corresponding values.

[CMake]: www.cmake.org
[git submodule]: http://git-scm.com/docs/git-submodule
[compatibility library]: https://github.com/foonathan/compatibility
[heap_allocator]: \ref foonathan::memory::heap_allocator
[options]: md_doc_options.html