1 Building modules out of tree {#outoftree}
2 ============================
4 Normally to build an %IMP module it is placed in the `modules` subdirectory
5 together with the rest of the %IMP source code and then all of %IMP is
6 built, as per the [installation instructions](@ref installation_source).
7 However,
this makes building a module an expensive process (as the build
8 system needs to check whether any part of %IMP has changed, not just the
9 module itself) and it is awkward to build a module against multiple
10 versions of %IMP,
for example against both the latest stable release and
11 a more recent nightly build.
13 An alternative is to build one or more %IMP modules
'out of tree', treating
14 them as their own [CMake](https:
15 directories, and pointing them to existing %IMP installation(s) using
16 %IMP's [existing CMake configuration](@ref uselibrary).
20 Out of tree modules can be maintained in one of two ways:
22 1. A top-level `modules` directory containing a number of subdirectories,
23 one per module; the name of each subdirectory is the name of the module.
24 This mimics the way %IMP itself maintains multiple modules.
25 2. All of a single module
's files can be placed in the top-level directory,
26 as is done for the [PMI](https://github.com/salilab/pmi/) module. This
27 has the advantage that the module can also be cloned directly into
28 %IMP's `modules` directory and built
'in tree', as well.
30 ## CMake configuration
32 Place the [FindIMP.cmake](https:
33 file into a suitable directory, say a `tools` subdirectory. This file will help
34 CMake to find the %IMP installation, as [described earlier](@ref uselibrary).
36 Make a top-level `CMakeLists.txt` file. This file
37 - Adds the `tools` directory to the CMake search path, so that CMake can
39 - Finds the %IMP package;
40 - Uses the `imp_build_module` CMake macro, provided in %IMP
's CMake
41 configuration, to build the module;
42 - For the single module case, detect an 'in tree
' build and fall back to
43 using %IMP's own CMake scripts.
45 A suitable `CMakeLists.txt` can be found in the
46 [PMI repository](https:
47 all that needs to be changed is `CMAKE_MODULE_PATH` (
if `FindIMP.cmake` was
48 not put in the `tools` directory) and the second argument to
49 `imp_build_module`, which is the module name. (If multiple modules are
50 being built under the `modules` directory,
this second argument should
51 be omitted - the module names will match those of the subdirectories.)
53 If you also need to use [RMF](https:
54 this should be searched
for separately; add the
55 [FindRMF.cmake](https:
56 file and add a suitable `find_package` call to `CMakeLists.txt` after the
57 search
for %IMP. A suitable `CMakeLists.txt` can be found in the
58 [npctransport repository](https:
59 This is needed because
while RMF is often bundled with %IMP, it can also be
60 installed separately (
this is the
case,
for example, with some of the
65 The module can now be built like any other CMake project - i.e. make a
66 build directory, and run CMake in that build directory, giving it the
67 path to the module source code. (You may need to set the `IMP_DIR` variable
68 to help CMake find %IMP.)
70 ## Testing and running
72 After a successful build, the build directory will contain a
73 `setup_environment.sh` script. This can be used just like that in %IMP
74 itself. It will add both the out of tree module(s) and %IMP to the search
75 path so that the module can be tested or used.