8000 Resolves #4 · jinja2cpp/jinja2cpp.github.io@bda8086 · GitHub
[go: up one dir, main page]
Skip to content

Commit bda8086

Browse files
flexferrumflexferrum
committed
Resolves #4
Actualize instructions for build and install
1 parent 1832cff commit bda8086

File tree

1 file changed

+99
-54
lines changed

1 file changed

+99
-54
lines changed

‎docs/build_and_install.md

Lines changed: 99 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,29 @@ nav_order: 4
1515

1616
## Supported compilers
1717
Compilation of Jinja2C++ tested on the following compilers (with C++14 enabled feature):
18-
- Linux gcc 5.0
19-
- Linux gcc 6.0
20-
- Linux gcc 7.0
21-
- Linux clang 5.0
22-
- Microsoft Visual Studio 2015 x86, x64
23-
- Microsoft Visual Studio 2017 x86, x64
18+
- Linux gcc 5.0 - 9
19+
- Linux clang 5.0 - 8
20+
- MacOS X-Code 9 - 11
21+
- Microsoft Visual Studio 2015-2019 x86, x64
2422

2523
## Dependencies
2624
Jinja2C++ has several external dependencies:
27-
- `boost` library (at least version 1.55)
25+
- `boost` library (at least version 1.65)
2826
- `nonstd::expected-lite` [https://github.com/martinmoene/expected-lite](https://github.com/martinmoene/expected-lite)
2927
- `nonstd::variant-lite` [https://github.com/martinmoene/variant-lite](https://github.com/martinmoene/variant-lite)
30-
- `nonstd::value-ptr-lite` [https://github.com/martinmoene/value-ptr-lite](https://github.com/martinmoene/value-ptr-lite)
3128
- `nonstd::optional-lite` [https://github.com/martinmoene/optional-lite](https://github.com/martinmoene/optional-lite)
29+
- `nonstd::string-view-lite` [https://github.com/martinmoene/string-view-lite](https://github.com/martinmoene/string-view-lite)
30+
- `fmtlib::fmt` [https://github.com/fmtlib/fmt](https://github.com/fmtlib/fmt)
31+
For testing purposes:
32+
- `rapidjson` [https://github.com/Tencent/rapidjson](https://github.com/Tencent/rapidjson)
33+
- `nlohmannjson` [https://github.com/nlohmann/json](https://github.com/nlohmann/json)
3234

3335
## Build and install
34-
In order to compile Jinja2C++ you need:
3536

36-
1. Install CMake build system (at least version 3.0)
37+
### The simplest case
38+
In simplest case, if you don't want to understand Jinja2C++ build script internals, you can follow these easy steps. Jinja2C++ library is shipped with all dependencies as a submodules and can use them. So, you have to:
39+
40+
1. Install CMake build system (at least version 3.5)
3741
2. Clone jinja2cpp repository and update submodules:
3842
```
3943
> git clone https://github.com/jinja2cpp/Jinja2Cpp.git
@@ -47,17 +51,17 @@ In order to compile Jinja2C++ you need:
4751
4. Run CMake and build the library:
4852
```
4953
> cd .build
50-
> cmake .. -DCMAKE_INSTALL_PREFIX=<path to install folder>
54+
> cmake .. -DCMAKE_INSTALL_PREFIX=<path to install folder> -DJINJA2_DEPS_MODE=internal
5155
> cmake --build . --target install
5256
```
53-
"Path to install folder" here is a path to the folder where you want to install Jinja2Cpp lib.
54-
5. Install library:
57+
"Path to install folder" here is a path to the folder where you want to install Jinja2Cpp lib. `JINJA2_DEPS_MODE` define with `internal` value creates the build script which will take external dependencies from the submodules.
58+
5. Build library:
5559
```
56-
> cmake --build . --target install
60+
> cmake --build .
5761
```
58-
6. Also you can run the tests:
62+
6. Install library (if necessary):
5963
```
60-
> ctest -C Release
64+
> cmake --build .
6165
```
6266

6367
### Use with conan.io dependency manager
@@ -67,7 +71,7 @@ Jinja2C++ can be used as conan.io package. In this case you should do the follow
6771
2. Register the following remote conan.io repositories:
6872
- https://api.bintray.com/conan/martinmoene/nonstd-lite
6973
- https://api.bintray.com/conan/bincrafters/public-conan
70-
- https://api.bintray.com/conan/manu343726/conan-packages
74+
- https://api.bintray.com/conan/flexferrum/conan-packages
7175

7276
The sample command is: `conan remote add martin https://api.bintray.com/conan/martinmoene/nonstd-lite`
7377
3. Add reference to Jinja2C++ package (`jinja2cpp/0.9.1@Manu343726/testing`) to your conanfile.txt, conanfile.py or CMakeLists.txt. For instance, with usage of `conan-cmake` integration it could be written this way:
@@ -99,57 +103,98 @@ set_target_properties (${TARGET_NAME} PROPERTIES
99103
100104
```
101105

106+
### Dependency management
107+
108+
Different projects require follow different ways for dependencies management. In some cases it's enough to build Jinja2C++ with the internal dependencies only. In other cases it could be necessary that Jinja2C++ use the externally-provided libraries (for instance, boost). To handle this cases Jinja2C++ supports several external dependencies management modes. This modes control via `JINJA2CPP_DEPS_MODE` variable.
109+
110+
#### 'internal' mode
111+
112+
In this mode Jinja2C++ will take all necessary dependencies (both for library build and tests build) from the submodules. This mode suitable when your project has no other dependencies or these dependencies aren't shared with Jinja2C++ deps. `cmake` invocation for this mode is quite simple:
113+
```
114+
> cmake <path_to_jinja2cpp_root> -DCMAKE_BUILD_TYPE=Release -DJINJA2CPP_DEPS_MODE=internal
115+
```
116+
117+
This mode is default for the upstream (`master`) branch. But for releases branch you need to specify this mode manually.
118+
119+
Sample projects for this mode can be found here: [https://github.com/jinja2cpp/examples-build/tree/master/subproject/internal](https://github.com/jinja2cpp/examples-build/tree/master/subproject/internal) and here: [https://github.com/jinja2cpp/examples-build/tree/master/external/internal](https://github.com/jinja2cpp/examples-build/tree/master/external/internal).
120+
121+
#### 'external-boost' mode
122+
123+
The `boost` library is wildly used (except of other Jinja2C++ dependencies), so it's possible to build Jinja2C++ with only `boost` provided as an external dependencies. In this case Jinja2C++ will take `boost` from the outside of the project tree, but all other dependencies will be taken from the submodules. Jinja2C++ build system tries to find boost with the standard `find_package` approach, so, it's necessary for this mode that path to the `boost` is provided with the standard ways (such as `BOOST_ROOT` environment variable). `cmake` invocation for this mode is also quite simple:
124+
```
125+
> cmake <path_to_jinja2cpp_root> -DCMAKE_BUILD_TYPE=Release -DJINJA2CPP_DEPS_MODE=external-boost
126+
```
127+
128+
Sample projects for this mode can be found here: [https://github.com/jinja2cpp/examples-build/tree/master/subproject/external_boost](https://github.com/jinja2cpp/examples-build/tree/master/subproject/external_boost) and here: [https://github.com/jinja2cpp/examples-build/tree/master/external/external_boost](https://github.com/jinja2cpp/examples-build/tree/master/external/external_boost).
129+
130+
#### 'external'
131+
132+
In this mode all Jinja2C++ build system tries to find all necessary dependencies outside the project tree. Path to the projects should be provided via `CMAKE_PREFIX_PATH` variable. This mode is suitable when you want to handle all external libs for your project manually and separately. `cmake` invocation for this mode is also quite simple:
133+
```
134+
cmake <path_to_jinja2cpp_root> -DCMAKE_BUILD_TYPE=Release -DJINJA2CPP_BUILD_TESTS=OFF -DJINJA2CPP_DEPS_MODE=external -DCMAKE_PREFIX_PATH="thirdparty/expected-lite;thirdparty/variant-lite;thirdparty/optional-lite;thirdparty/string-view-lite;thirdparty/fmt
135+
```
136+
This mode is default for the releases branches in order to make archives with Jinja2C++ sources compilable by default.
137+
138+
Sample projects for this mode can be found here: [https://github.com/jinja2cpp/examples-build/tree/master/subproject/external](https://github.com/jinja2cpp/examples-build/tree/master/subproject/external) and here: [https://github.com/jinja2cpp/examples-build/tree/master/external/external](https://github.com/jinja2cpp/examples-build/tree/master/external/external).
139+
102140
### Additional CMake build flags
103141
You can define (via -D command line CMake option) the following build flags:
104142

105143
- **JINJA2CPP_BUILD_TESTS** (default TRUE) - to build or not to Jinja2C++ tests.
106144
- **JINJA2CPP_STRICT_WARNINGS** (default TRUE) - Enable strict mode compile-warnings(-Wall -Werror and etc).
107-
- **JINJA2CPP_BUILD_SHARED** (default OFF) - Specify Jinja2C++ library library link type.
108145
- **MSVC_RUNTIME_TYPE** (default /MD) - MSVC runtime type to link with (if you use Microsoft Visual Studio compiler).
109-
- **JINJA2CPP_DEPS_MODE** (default "internal") - modes for dependencies handling. Following values possible:
110-
- `internal` In this mode Jinja2C++ build script uses dependencies (include `boost`) shipped as subprojects. Nothing needs to be provided externally.
111-
- `external-boost` In this mode Jinja2C++ build script uses only `boost` as externally-provided dependency. All other dependencies taken from subprojects.
112-
- `external` In this mode all dependencies should be provided externally. Paths to `boost`, `nonstd-*` libs etc. should be specified via standard CMake variables (like `CMAKE_PREFIX_PATH` or libname_DIR)
113-
- `conan-build` Special mode for building Jinja2C++ via conan recipe.
114-
115-
## Dependency management modes
116-
TODO:
117146

118147
## Link with you projects
119-
Jinja2C++ is shipped with cmake finder scripts. So you can:
120-
121-
1. Include Jinja2C++ cmake scripts to the project:
148+
Jinja2C++ is a CMake project and follow the standard ways of the CMake project `find` script implementation. So, you can either include Jinja2C++ as a subproject of your project. In this case you should link against `jinja2cpp` target. All necessary settings are already associated with this target. For instance:
122149
```cmake
123-
list (APPEND CMAKE_MODULE_PATH ${JINJA2CPP_INSTALL_DIR}/lib/jinja2cpp)
150+
cmake_minimum_required (VERSION 3.0.0 FATAL_ERROR)
151+
project (Jinja2CppBuildTest CXX)
152+
153+
set (TARGET_NAME jinja2cpp_build_test)
154+
155+
set (JINJA2CPP_DEPS_MODE internal CACHE STRING "" FORCE)
156+
157+
add_subdirectory (${JINJA2CPP_DIR} ${CMAKE_CURRENT_BINARY_DIR}/thirdparty/jinja2cpp)
158+
159+
add_executable (${TARGET_NAME} main.cpp)
160+
161+
target_link_libraries (${TARGET_NAME} jinja2cpp)
162+
set_target_properties (${TARGET_NAME} PROPERTIES
163+
CXX_STANDARD 14
164+
CXX_STANDARD_REQUIRED ON)
124165
```
125-
2. Use regular 'find' script:
126-
```cmake
127-
find_package(jinja2cpp)
166+
167+
Sample project for this build type you can find here: [https://github.com/jinja2cpp/examples-build/tree/master/subproject/internal](https://github.com/jinja2cpp/examples-build/tree/master/subproject/internal)
168+
169+
Or you can build Jinja2C++ library separately, install it and the find it via `find_package` cmake function. In this case:
170+
1. You should build Jinja2C++ with `CMAKE_INSTALL_PREFIX` variable defined and then install it:
171+
```shell script
172+
cmake thirdparty/Jinja2Cpp -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../.jinja2cpp-install -DJINJA2CPP_BUILD_TESTS=OFF
173+
cmake --build . --target install
128174
```
129-
3. Add found paths to the project settings:
130-
```cmake
131-
#...
132-
include_directories(
133-
#...
134-
${JINJA2CPP_INCLUDE_DIR}
135-
)
136-
137-
target_link_libraries(YourTarget
138-
#...
139-
${JINJA2CPP_LIBRARY}
140-
)
141-
#...
142-
```
143-
or just link with Jinja2Cpp target:
175+
2. You should provide path to the Jinja2C++ library directory to the `cmake` invocation of your project:
176+
```shell script
177+
cmake .. -DCMAKE_BUILD_TYPE=Release -Djinja2cpp_DIR=../.jinja2cpp-install/lib/jinja2cpp
178+
```
179+
3. In the CMake script of your project you should find Jinja2C++ with the `find_package` invocation:
144180
```cmake
145-
#...
146-
target_link_libraries(YourTarget
147-
#...
148-
jinja2cpp
149-
)
150-
#...
181+
cmake_minimum_required (VERSION 3.0.0 FATAL_ERROR)
182+
project (Jinja2CppBuildTest CXX)
183+
184+
set (TARGET_NAME jinja2cpp_build_test)
185+
set (CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/.jinja2cpp-install)
186+
187+
find_package(jinja2cpp REQUIRED)
188+
189+
add_executable (${TARGET_NAME} main.cpp)
190+
191+
target_link_libraries (${TARGET_NAME} jinja2cpp)
192+
set_target_properties (${TARGET_NAME} PROPERTIES
193+
CXX_STANDARD 14
194+
CXX_STANDARD_REQUIRED ON)
151195
```
152196

197+
153198
## Build with C++17 standard enabled
154199
In case of C++17 standard enabled for your project you should define `variant_CONFIG_SELECT_VARIANT=variant_VARIANT_NONSTD` macro in the build settings.
155200

0 commit comments

Comments
 (0)
0