Getting Started #
This library uses the cross-platform tool CMake to orchestrate the building and testing process on Linux, MacOS, and Windows.
ldsCtrlEst requires Armadillo for linear algebra as well as HDF5 for saving output.
vcpkg is a cross-platform C++ package manager which allows us to easily install and use the dependencies in isolation.
Tested Configurations #
Building C++ libraries with complex dependencies can be tricky business—in our experience builds have inexplicably worked in one environment and failed in another. To save you time, sweat, and tears, we suggest you simply use one of the following setups we know work fairly reliably, using the
RelWithDebInfo build type in the CMake configure command (
- Ubuntu 18.04 with GCC 7.5 compiler
- macOS 11 (Big Sur) with Apple Clang 12 compiler
- Windows 10 with Visual Studio 16.11 (2019 release) and Clang 12 compiler
That being said, if you want to debug a build for a single platform, here are some things you can try:
- Use different compilers (or even different versions of a single compiler)
- Use different versions of vcpkg (which you can control by checking out a different commit in the vcpkg submodule)
Mac Pre-requisities #
Xcode Command Line Tools will get you clang, gcc, make, and git:
Homebrew is “The Missing Package Manager for macOS” which will make installing lots of things easy. Install like this:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
You can then use it to install CMake and gfortran:
brew install cmake gfortran
Linux Pre-requisites #
You’ll need Git, CMake, GCC, gfortran, etc.
sudo apt install git cmake pkg-config gfortran curl zip unzip tar build-essential
Windows Installation #
Look here for Windows-specific instructions.
Downloading the Library #
First, clone the repository along with submodules:
git clone https://github.com/cloctools/lds-ctrl-est.git cd lds-ctrl-est git submodule update --init
Compilation + Installation #
Now generate the cache and build using your IDE or from the command line as follows.
mkdir build && cd build cmake .. cmake --build .
The first time,
vcpkg will automatically install dependencies into
[build directory]/vcpkg_installed/, which will likely take about 10-20 minutes.
If you want to use
vcpkg set up somewhere besides this repo’s submodule, add
-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake to the
cmake command directly or through your IDE’s settings.
You can verify the build is working by running
ctest from the build folder, which runs all the example scripts.
This project is configured/compiled/installed by way of CMake and (on Unix-based operating systems) GNU Make. For configuration with CMake, there are three available options.
LDSCTRLEST_BUILD_EXAMPLES: [default=ON] whether to build example programs located under
examples/in the source tree
LDSCTRLEST_BUILD_FIT: [default=ON] whether to build the auxiliary fitting portion of the source code that is not pertinent to control implementation
LDSCTRLEST_BUILD_STATIC: [default=ON] whether to statically link against OpenBLAS and create a static ldsCtrlEst library for future use
n.b., If both options 2 and 3 are enabled, Matlab/Octave mex functions will be compiled for exposing some of the fitting functionality to Matlab/Octave, assuming these programs are installed.
Below are example usages of
cmake to configure/build the library.
For basic project build & install
cd /path/to/repository mkdir build && cd build cmake .. #configure build cmake --build #build the project sudo make install #[optional] installs to default location (OS-specific)
To set the install prefix
cd /path/to/repository mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=/your/install/prefix .. #configure build with chosen install location cmake --build #build the project make install #install to /your/install/prefix
To build the bare bones project, excluding fit code and Matlab mex code.
cd /path/to/repository mkdir build && cd build cmake -DLDSCTRLEST_BUILD_FIT=0 .. #configure not to build the fitting portion of library make #build the project
n.b., If you choose not to install the library or install it to the non-default location, ensure you have updated the following environment variables on Unix-based operating systems.
LD_LIBRARY_PATH: search path for dynamically loaded libraries
PKG_CONFIG_PATH: search path for
On Windows, you may need to add the build location to the PATH environment variable for the library to be used elsewhere.
Python bindings package
LDSCTRLEST_BUILD_PYTHON setting (off by default) and the
pybind11 submodule initialized, you can build Python bindings. You will probably want to specify the installation of Python to use by adding a
-DPython3_ROOT_DIR=[path/to/install/dir] argument to the CMake cache generation command (the first one) so CMake doesn’t use an undesired version. That environment needs to have NumPy installed.
cmake --build . --target python_modules
The bindings need to be generated just once per Python version. Once the build is complete, navigate to the
[build location]/python folder and run
pip install . to make it importable anywhere for your current environment. The file structure only works correctly for this if you use a single-config generator like Ninja or Make, though. You can verify the installation was successful by running
pytest from the
build/python directory (
pip install pytest matplotlib first if you need to).
python/ldsctrlest/README.md for usage details.
Also, beware that a single build will probably not work for both the standalone library and the Python package, since the conversion between NumPy and Armadillo alters the way Armadillo allocates memory. In this case you may want to build once with
-DLDSCTRLEST_BUILD_PYTHON=ON, install the package, then again with
-DLDSCTRLEST_BUILD_PYTHON=OFF for the pure C++ build to work correctly.
Common issues #
- “I have built the library and installed it in a non-default location. In building my own project linking against
pkg-configcannot find the library or its configuration information.”
pkg-config cannot find the required configuration files for your project to link against ldsCtrlEst, make sure that these utilities know to look for them in the non-default location where you installed the library. For
cmake this means adding your chosen install prefix to the environment variable
CMAKE_PREFIX_PATH. Similarly, for
pkg-config you need to add
your/install/prefix/lib/pkgconfig to its search path,
PKG_CONFIG_PATH. Assuming a Unix shell whose login startup file is
~/.profile and ldsCtrlEst was installed using prefix
your/install/prefix, add the following to
export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:/your/install/prefix export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/your/install/prefix
- vcpkg fails on configuration
./bootstrap-vcpkg from the
vcpkg folder and try again. If that doesn’t work, try updating vcpkg to a newer version (in the source control tab, click on the commit hash by the vcpkg repo then select from the dropdown) and running
boostsrap-vcpkg again. You can also try upgrading your system (e.g.,
Could not find Python3 (missing: Python3_NumPy_INCLUDE_DIRS NumPy)
Make sure NumPy is installed in the Python environment you specified. If CMake still can’t find it, you may need to tell CMake exactly where to find it by adding an argument to the configure command:
-DPython3_NumPy_INCLUDE_DIR=.... You can find that location like this:
python -c 'import numpy; print(numpy.get_include())'