Please report any issues with BASIS, including bug reports, feature requests, or support questions, on GitHub. Before opening a new issue, we recommend a look at the frequently asked questions below and a search of the already reported open issues.
Can I still use standard CMake calls such as add_library, or is some BASIS functionality lost?
Probably. However, you will definitely lose much of the useful functionality that BASIS was created to provide. This kind of usage has also not been heavily tested so it is not recommended. The BASIS philosophy is definitely that a project that switches to BASIS uses the basis_* CMake commands wherever possible. Consider BASIS an extension to CMake, but if you run into issues you can file a ticket and we will attempt to address the problem.
Can I use the <Package>Config.cmake files of projects that do not use BASIS?
In <Package>Config.cmake files of other projects, it is fine that there will be standard CMake commands add include/library directories or import targets. BASIS is “smart” enough to extract this information properly by overriding the standard CMake commands.
Do library targets have to be manually exported?
No. This is taken care of by the functions found in the internal ExportTools.cmake module, including executable targets which correspond to executable Python, Perl, BASH scripts, or executable binaries generated by the MATLAB Compiler.
Does the BASISConfig.cmake file define all of the exported library targets?
As typical for CMake, import statements for exported targets are written to “export files”. These are included by the BASISUse.cmake file which should be included by other packages which use BASIS as follows:
find_package(BASIS REQUIRED)
include(${BASIS_USE_FILE})
This is done already by the basis_use_package() function which in turn
is called by basis_find_packages() for all project dependencies right after
the respective basis_find_package() call. In case of BASIS itself,
the basis_use_package(BASIS)
is called by the basis_project_begin() command
which also calls basis_find_packages().
Thus, all you need to do is add a call to basis_project_begin() to the root CMakeLists.txt file of your project. See the root CMakeLists.txt of the default project template included with BASIS for an example.
Is there an easy way for users to get a list of the exported targets in a module?
No. This should probably be part of the documentation of each respective package/module.
Generally with CMake, you would have a look at the exports file of a package that
can usually be found right next to the CMake package configuration file (<Package>Config.cmake
).
Look into the build directory of your BASIS build for an example. There you find the following files:
File name | Description |
---|---|
BASISConfig.cmake | Package configuration file which is included by CMake’s find_package command. |
BASISExports.cmake | Import statements for exported targets. |
BASISCustomExports.cmake | Import statements for exported custom targets. |
BASISUse.cmake | File to be included by users. Imports the exported targets. |
Note
These file are generated by BASIS for every project that uses it,
where BASIS
is replaced by package name.
Note that these files contain the paths to the libraries and executables in the build tree.
For each of these, BASIS configures also a second version which contains then the paths for
the installation tree which are all relative to the location of the <Package>Config.cmake
file and made absolute upon inclusion of these files.
The export files are generated by the internal CMake function basis_export_targets(). This function not only exports the custom targets of a project, but also calls CMake’s export and install(EXPORT) commands for built-in targets, i.e., C/C++ executables and libraries. This happens upon project “finalization”, i.e., basis_project_end(), which must be called at the end of each root CMakeLists.txt, including the CMakeLists.txt file in the top-level directory of each project module.
The exported target names are all the “fully qualified target UIDs” as used internally
by BASIS to avoid target name conflicts between packages. The target name specified
as argument to the basis_add_*
target commands is prepended by the name of the package
(i.e., top-level project name in case of modules, respectively, the PACKAGE_NAME
specified in the BasisProject.cmake
file) and separated by a dot (.
).
For example, the BASIS Utilities library of the CMake BASIS package has the exported
target name basis.utilities
.
When two modules belong to the same package, the package name prefix of the target names can be omitted when calling basis_target_link_libraries(), for example.