diff options
author | Vegard Sjonfjell <vegardsjo@gmail.com> | 2016-07-08 15:55:22 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2016-07-08 15:55:22 +0200 |
commit | e460f999b6cd91a859271ea3e5eadb84e1abb742 (patch) | |
tree | 75106c5322aab156c26cb57d045009e18bbc0e79 /README-cmake.md | |
parent | a2d774f4d8412862b425de61d7c8ac8d82c6e593 (diff) |
CMake guide (#331)
* CMake guide
* Remove reference to interal doc
Diffstat (limited to 'README-cmake.md')
-rw-r--r-- | README-cmake.md | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/README-cmake.md b/README-cmake.md new file mode 100644 index 00000000000..192e63a77b5 --- /dev/null +++ b/README-cmake.md @@ -0,0 +1,203 @@ +CMake Guide +=========== + +This is a guide describing how to use the Vespa specific CMake functions and macros. +The Vespa CMake setup wraps or combines together a number of CMake functions in order to simplify defining library and executable targets, and to automatically create targets that depend on a subset of targets. + +# `vespa_add_library` +The `vespa_add_library` function is used to define a library. +At the least, it takes a target name, and the library's source files. + + vespa_add_library(<target-name> [STATIC|OBJECT|INTERFACE|TEST] + [SOURCES <source-file> [source-file ...]] + [OUTPUT_NAME <name-of-library>] + [DEPENDS <other-target|external-library> [other-target|external-library ...]] + [AFTER <other-target> [other-target ...]] + ) + +## Parameters + +### STATIC +Parameter denoting that this is a static library. +If this parameter is omitted, the library is shared. + +### OBJECT +Parameter denoting that this is an object library. +This parameter is optional. + +### INTERFACE +Parameter denoting that this is an interface library, that is, a library producing no object files, for example a collection of headers. +This parameter is optional. + +### TEST +Parameter denoting that this is a "test library". +Test libraries are not added to the `all` target if the CMake cached variable `EXCLUDE_TESTS_FROM_ALL` is true. + +### SOURCES [source-file ...] +The `SOURCES` parameter takes a list of source files for this library. +This parameter can be omitted if you're defining an interface or config-only library. + +### OUTPUT_NAME <name-of-library> +Specifies the base name of the produced library file (SONAME). E.g., in Linux, if the output name is `stroustrup`, the library file would be named `libstroustrup.so` +This parameter is optional. +If it is not set, the library takes its name from the target name. + +### DEPENDS [other-target-or-lib ...] +The `DEPENDS` parameter takes a list of targets or external libraries to link to, with the following exception: +* If `target-name` is an object library and `other-target-or-lib` is another target, instead add an dependency on `other-target-or-lib` (like `AFTER`). +This parameter is optional. + +### AFTER [other-target ...] +Add a (weak) build dependency on every target in the given list, requiring only that the target is built before `target-name`. +This parameter is optional. + + +# `vespa_add_executable` +The `vespa_add_executable` function is used to define an executable/application. +At the least, the function takes a target name, and the executable's source files. + + vespa_add_executable(<target-name> [TEST] + SOURCES <source-file> [source-file ...] + [OUTPUT_NAME <name-of-executable>] + [DEPENDS <other-target|external-library> [other-target|external-library ...]] + [AFTER <other-target> [other-target ...]] + ) + +### TEST +Parameter denoting that this is a "test executable". +Test executables are not added to the `all` target if the CMake cached variable `EXCLUDE_TESTS_FROM_ALL` is set to a true value. + +### SOURCES [source_file ...] +The `SOURCES` parameter takes a list of source files for this executable. +This parameter is required. + +### OUTPUT-NAME <name-of-executable> +Specifies the base name of the produced executable file (omitting the file extension). +This parameter is optional. +If this parameter is not set, the executable takes its name from the target name. + +### DEPENDS [other-target-or-lib ...] +The `DEPENDS` parameter takes a list of targets or external libraries to link to. +This parameter is optional. + +### AFTER [other-target ...] +Add a (weak) build dependency on every target in the given list, requiring only that the target is built before `target-name`. +This parameter is optional. + + +# `vespa_generate_config` + + vespa_generate_config(<for-target-name> <config-def-path>) + +`vespa_generate_config` generates from config definition (`.def`) files. + +`<for-target-name>` is the name of the target you want the generated config object to be linked to. +This target needs to have been defined before you call `vespa_generate_config`. + + +# `vespa_define_module` + +The `vespa_define_module` defines a *module*. +A module is a collection of targets under a directory root (e.g. `searchlib`) +The name of the module is the same as the directory name where the module is defined. +The module definition is used to specify common dependencies for every target defined (by use of `vespa_add_library/executable`) under the module. + + + vespa_define_module( + DEPENDS + fastos + vespalib + bjarnelib + + EXTERNAL_DEPENDS + xml2 + + LIBS + src/vespa/lib1 + src/vespa/lib2 + + LIB_DEPENDS + docproc2000 + + LIB_EXTERNAL_DEPENDS + andrei_allocators + + APPS + src/apps/app1 + src/apps/app2 + + APP_DEPENDS + searchlib + + APP_EXTERNAL_DEPENDS + stroustrup_utils + + TESTS + src/tests/app1_test + src/tests/app2_test + + TEST_DEPENDS + homemade_printf_from_uni + + TEST_EXTERNAL_DEPENDS + andrei_allocators + cppunit + ) + +Directories containing `CMakeLists.txt` with library/executable definitions are divided into three categories by the use of the following `vespa_define_module` parameters: `LIBS` (libraries), `APPS` (applications), and `TESTS`. + +You can define common target dependencies for all targets defined with `vespa_add_library/executable` by listing them using the `LIB_DEPENDS`/`APP_DEPENDS`/`TEST_DEPENDS` parameters. +Use `LIB_EXTERNAL_DEPENDS`/`APP_EXTERNAL_DEPENDS`/`TEST_EXTERNAL_DEPENDS` for external library dependencies (this is different from `DEPENDS` in `vespa_add_library/executable` which can be used to specify both internal target dependencies and external library dependencies). +Finally, you can use `DEPENDS` and `EXTERNAL_DEPENDS` to specify, respectively, common target dependencies and common external library dependencies for all the categories. + +The definitions within these directories need not strictly adhere to categories in which their parent directory are listed; the categories are simply a way to split common dependencies into three disjoint sets. + + +# `vespa_add_test` + + vespa_add_test(NAME <test-name> [NO_VALGRIND|RUN_SERIAL|BENCHMARK] + COMMAND <command> [command ...] + [WORKING_DIRECTORY <working-directory>] + [ENVIRONMENT <environment-stringlist>] + ) + +`vespa_add_test` defines a test using the CTest integration of CMake. +Have in mind that tests are **not** targets, so they can't depend on other targets. +If your test depends on a target being built for it to run, you need to build that target first. +Running the test will not trigger building targets required by the test. + +`vespa_add_test` takes the following parameters. + +### NAME <test-name> +Name of test as shown by the output of CTest and used as an identifier for running tests based on a regex match on test names. +This parameter is required. + +### NO_VALGRIND +Do not run this test under Valgrind even if the CMake variable `VALGRIND_UNIT_TESTS` is true. +This parameter is optional and defaults to false. + +### RUN_SERIAL +Do not run this test in parallel with any other test. +This parameter is optional and defaults to false. + +### BENCHMARK +Only run this test if the CMake variable `RUN_BENCHMARKS` is true. +This parameter is optional and defaults to false. + +### COMMAND +Either the name of a target that produces an executable (whereby the test will run the executable) or a command line that is to be executed when the test runs. +This parameter is required. + +### WORKING_DIRECTORY +Working directory when running the test. +This parameter is optional and defaults to `CMAKE_CURRENT_BINARY_DIR`. + +### ENVIRONMENT +A quoted list in the form `"NAME1=value1;NAME2=value2"` + + +# `vespa_install_script` + + vespa_install_script(<filename> [<to-filename>] <destination-dir>) + +Install (copy) a shell script `<filename>`, optionally as the destination filename `<to-filename>`, to the directory `<destination-dir>` under the install prefix, and set correct executable permissions. |