IMP logo
IMP Manual  for IMP version 2.16.0
extdepends.md
1 Adding external dependencies {#extdepends}
2 ============================
3 
4 [TOC]
5 
6 # Introduction # {#extdep_intro}
7 
8 You can have an %IMP module depend on some external library, for example
9 to take advantage of a method implemented in that library, or to link
10 %IMP with another piece of software at runtime.
11 
12 # Considerations # {#extdep_consider}
13 
14 Think very carefully before introducing a new external dependency. Each
15 additional dependency makes it harder for people to use your code.
16 If you do need to add a dependency, it needs to be open source and available
17 under a suitably permissive license (for %example if it is available under
18 the GPL then you cannot license your module as LGPL, but will need to also
19 make it GPL).
20 
21 Generally if you need to add a new dependency you should probably also put
22 your code in a new module, rather than adding it to an existing module. That
23 way, people that elect not to install that dependency will only be deprived
24 of your code, not of the existing module.
25 
26 # Simple dependencies # {#extdep_simple}
27 
28 The simplest way to add a C/C++ dependency `foo` is to create a file
29 `foo.description` in the `dependency` subdirectory of your module. This is a
30 simple text file containing several variables:
31 
32 - `headers`: a colon-separated list of any C/C++ headers that need to be
33  included to use the dependency.
34 - `libraries`: a colon-separated list of any libraries that need to be
35  linked against to use the dependency. (There is a similar `extra_libraries`
36  variable, if needed, for libraries that aren't part of the dependency but
37  that need to also be linked in order for it to work.)
38 - `body`: a fragment of C++ code that uses the dependency.
39 
40 When CMake is run, it will use the variables in `foo.description` to build
41 a small test program in order to make sure the dependency is available and
42 that it works. See `modules/kernel/dependency/GPerfTools.description` for
43 an example.
44 
45 # More complex dependencies # {#extdep_complex}
46 
47 For more complex dependencies, you can also create a `foo.cmake` file
48 containing arbitrary CMake instructions to configure the dependency. See for
49 example `modules/rmf/dependency/RMF.cmake`.
50 
51 # Using the dependency # {#extdep_using}
52 
53 The next step in adding a `foo` dependency is to list `foo` in the module's
54 `dependencies.py` file. `foo` can be listed either in that file's
55 `required_dependencies` variable or in `optional_dependencies`, both of
56 which are colon-separated lists of external dependencies. See for example
57 `modules/kernel/dependencies.py`.
58 
59 If placed in `required_dependencies`, the module cannot be built unless your
60 dependency is found. The module will be automatically linked against the
61 dependency.
62 
63 If placed in `optional_dependencies`, the module can be built either with
64 or without the dependency. If the dependency is available, a preprocessor
65 macro will be set when the module is built; protect your code with that
66 macro. For example, IMP::score_functor can be built with or without the
67 HDF5 library. Any code that requires HDF5 is conditional on the
68 `IMP_SCORE_FUNCTOR_USE_HDF5` preprocessor macro.