examples/subproject/README.md

   1 Example: marnav as subproject (git submodule/subtree)
   2 =====================================================
   3
   4 This is an example project, to show a way to use marnav as a subproject.
   5
   6 This demo uses the *ExternalProject* module from CMake.
   7
   8 **Note:** it is not advisable to test this demo using git submodule right here,
   9           copy this demo somewhere outside the repository.
  10
  11 **Note:** this is not a tutrial about git submodule.
  12
  13
  14 Directory Structure
  15 -------------------
  16
  17 ```
  18 marnav-demo
  19 +- cmake
  20 |  +- ExternMarnav.cmake
  21 |
  22 +- extern
  23 |  +- README.md
  24 |
  25 +- src
  26 |  +- CMakeLists.txt
  27 |  +- main.cpp
  28 |
  29 +- CMakeLists.txt
  30 +- README.md
  31 ```
  32
  33 with
  34
  35 - `cmake`  as the cmake module directory.
  36 - `extern` the place where submodules are being kept.
  37 - `src`    the source of the demo project.
  38
  39 For easier demonstration and testing purposes, the environment variable
  40 `MARNAV_SOURCE_DIR` needs to be set accordingly.
  41
  42
  43 Test
  44 ----
  45
  46 Copy the demo to some place, `/tmp/subproject` will do for now,
  47 and make it a repository. The variable `${PATH_TO_MARNAV}` points
  48 to you local clone. No need to set the variable, just replace it
  49 as you execute the following.
  50
  51 ```bash
  52 cp -R ${PATH_TO_MARNAV}/examples/subproject /tmp/
  53 cd /tmp/subproject
  54 git init
  55 git add *
  56 git commit -am "Initial Import"
  57 ```
  58
  59 Add the library as git submodule:
  60
  61 ```bash
  62 git submodule add ${PATH_TO_MARNAV} /tmp/subproject/extern/marnav
  63 ```
  64
  65 Build the library and demo:
  66
  67 ```bash
  68 export MARNAV_SOURCE_DIR=/tmp/subproject/extern/marnav
  69 cmake -H. -Bbuild
  70 cmake --build build
  71 ```
  72
  73 **Note:** the library part (release mode) of *marnav* is being built, no unit tests
  74           no tools and no examples. See `cmake/ExternMarnav.cmake` for build options.
  75