Support

Report Issue

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.

Frequently Asked Questions

Standard CMake Commands

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.

CMake Package Configuration

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.

Export of Build Targets

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.