-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Here, I've updated the build instructions for Conan 2.0, simplifying them significantly with the use of CMake's new `--preset` switch.
- Loading branch information
1 parent
bce2132
commit 859cd0f
Showing
1 changed file
with
101 additions
and
107 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,153 +1,147 @@ | ||
| libcosim - A co-simulation library for C++ | ||
| ========================================== | ||
| # libcosim - An open-source co-simulation library for C++ | ||
|
|
||
|  | ||
|  | ||
|
|
||
| This repository contains the OSP C++ library for co-simulations. | ||
|
|
||
| See [`CONTRIBUTING.md`] for contributor guidelines and [`LICENSE`] for | ||
| terms of use. | ||
| Libcosim was developed as part of the [Open Simulation Platform][OSP] (OSP). | ||
| See [`CONTRIBUTING.md`] for contributor guidelines and [`LICENSE`] for terms | ||
| of use. | ||
|
|
||
| The libcosim library is demonstrated in [cosim](https://github.com/open-simulation-platform/cosim-cli) and | ||
| [Cosim Demo Application](https://github.com/open-simulation-platform/cosim-demo-app). | ||
| The applications can be downloaded from their release pages: | ||
| - cosim [releases](https://github.com/open-simulation-platform/cosim-cli/releases) | ||
| - Cosim Demo Application [releases](https://github.com/open-simulation-platform/cosim-demo-app/releases) | ||
|
|
||
| How to use | ||
| ------------ | ||
| To use libcosim in your application you either build the library as described | ||
| in the section below or you can use conan. As libcosim is made available as a | ||
| conan package on https://osp.jfrog.io, you can include it in your application | ||
| following these steps: | ||
|
|
||
| * Install [Conan] version 2.x | ||
| * Add the OSP Conan repository as a remote: | ||
| ## How to use | ||
|
|
||
| conan remote add osp https://osp.jfrog.io/artifactory/api/conan/conan-local | ||
| * Include libcosim as a requirement in your conanfile | ||
| * Run `conan install` to aquire the libcosim package | ||
| The recommended way to include libcosim in your own projects is via the | ||
| [Conan] C/C++ package manager. First, you need to add the OSP package | ||
| repository to your remotes, like this: | ||
|
|
||
| [cosim], [cosim4j] and [Cosim Demo Application] are examples of how to use the libcosim with conan. | ||
| conan remote add osp https://osp.jfrog.io/artifactory/api/conan/conan-local | ||
|
|
||
| How to build | ||
| ------------ | ||
| Then, you can simply list `libcosim/<version>` as a requirement in your | ||
| conanfile. Note that libcosim requires Conan 2.x. | ||
|
|
||
| ### Required tools | ||
| Even if your project cannot use Conan for some reason, it is still possible to | ||
| use libcosim. In that case, you have to build it from source and manage the | ||
| dependency yourself. Instructions for building are in the next section. | ||
|
|
||
| * Compilers: [Visual Studio] >= 16.0/2019 (Windows), GCC >= 9 (Linux) | ||
| * Build tool: [CMake] >= 3.19 | ||
| * API documentation generator (optional): [Doxygen] | ||
| * Package manager (optional): [Conan] 2.x | ||
| For demonstrations of libcosim use, check out the OSP [Cosim] command-line | ||
| interface and [Cosim Demo Application]. | ||
|
|
||
| Throughout this guide, we will use Conan to manage dependencies. However, it | ||
| should be possible to use other package managers as well, such as [vcpkg], and | ||
| of course you can always build and install dependencies manually. | ||
| ### Other programming languages | ||
|
|
||
| ### Step 1: Configure Conan | ||
| Wrappers exist for other programming languages too: | ||
|
|
||
| First, add the OSP Conan repository as a remote: | ||
| * C++: [libcosimc] | ||
| * Python: [libcosimpy] | ||
| * Java/JVM: [cosim4j] | ||
|
|
||
| conan remote add osp https://osp.jfrog.io/artifactory/api/conan/conan-local | ||
| Note that none of them have complete support for all libcosim features. | ||
|
|
||
| Package revisions must be enabled. See [How to activate the revisions]. | ||
|
|
||
| As we will build the library using the *debug* configuration in this guide (as | ||
| opposed to *release*), we must use the Conan setting `build_type=Debug`. For | ||
| GCC, we also need to set `compiler.libcxx=libstdc++11`, because the library | ||
| makes heavy use of C++11/14/17 features. You can either change these settings | ||
| in your [Conan profile], or you can specify them using the `--settings` switch | ||
| when running `conan install` later. To do the former, add one or both of the | ||
| following lines to the appropriate profile(s): | ||
| ## How to build | ||
|
|
||
| build_type=Debug | ||
| compiler.libcxx=libstdc++11 | ||
| ### Step 0: Get your tools in order | ||
|
|
||
| Again, the second line should only be added if you are compiling with GCC. | ||
| The tools needed to build libcosim are: | ||
|
|
||
| * Compilers: [Visual Studio] >= 16.0/2019 (Windows), GCC >= 9 (Linux) | ||
| * Build tool: [CMake] >= 3.19 | ||
| * Package manager (optional): [Conan] 2.x | ||
| * API documentation generator (optional): [Doxygen] | ||
|
|
||
| In this guide, we will use Conan to download and configure libcosim's | ||
| dependencies. We strongly recommend that you do too, even when you're unable | ||
| to use it to incorporate libcosim in your own project afterwards. It *is* | ||
| possible to use other package managers or manage the dependencies yourself, | ||
| but then you're mostly on your own. (See the [CI without Conan] GitHub | ||
| actions workflow we've set up for an example of how to do it via the Debian | ||
| package manager.) | ||
|
|
||
| ### Step 2: Prepare build system | ||
| We will also assume that your CMake is version 3.23 or newer, even if | ||
| libcosim's minimum requirement is CMake 3.19. The reason is that this lets us | ||
| use the convenient `--preset` switch. If you need to use a slightly older | ||
| version, the [Conan CMakeToolchain documentation] has a simple workaround. | ||
|
|
||
| Now, we will create a directory to hold the build system and generated files, | ||
| use Conan to acquire dependencies, and run CMake to generate the build system. | ||
| ### Step 1: Install dependencies | ||
|
|
||
| We'll create the build directory as a subdirectory of our root source | ||
| directory—that is, the directory which contains this README file—and call it | ||
| `build`. Note, however, that it may be located anywhere and be called anything | ||
| you like. | ||
| First, make sure that you've added the OSP package repository to your Conan | ||
| remotes as shown in the previous section. Then, go to the root directory of | ||
| the libcosim source tree (i.e., the directory that contains this README | ||
| file) and run the following command: | ||
|
|
||
| From the libcosim source directory, create and enter the build directory: | ||
| conan install --build=missing . | ||
|
|
||
| mkdir build | ||
| cd build | ||
| This will install all dependencies, building the ones for which binary | ||
| packages weren't available online, and set up some configuration files for the | ||
| next steps. Add `--options="proxyfmu=True"` to the above command to enable | ||
| support for [proxy-fmu]. | ||
|
|
||
| Then, acquire dependencies with Conan: | ||
| ### Step 2: Generate build system | ||
|
|
||
| conan install .. --build=missing | ||
| Next, to generate the libcosim build system, run: | ||
|
|
||
| (You may also have to append `--settings build_type=Debug` and possibly | ||
| `--settings compiler.libcxx=libstdc++11` to this command; see Step 1 for more | ||
| information.) | ||
| cmake --preset=<config-preset-name> | ||
|
|
||
| #### proxyfmu | ||
| To include proxyfmu support, run conan install with the additional option: | ||
| ```bash | ||
| -o proxyfmu=True | ||
| ``` | ||
| where `<config-preset-name>` depends on the underlying toolchain. For Visual | ||
| Studio on Windows it will usually be `conan-default`, while for GCC/Make on | ||
| Linux it should be `conan-release` or `conan-debug`, depending on which build | ||
| type you want. (More precisely, it depends on whether a multi- or | ||
| single-configuration CMake generator is used. Consult the | ||
| [Conan CMakeToolchain documentation] for details on presets and their names.) | ||
|
|
||
| Now, we can run CMake to generate the build system. (If you have not installed | ||
| Doxygen at this point, append `-DLIBCOSIM_BUILD_APIDOC=OFF` to the next command | ||
| to disable API documentation generation.) | ||
| Note that the build type you choose must match one set up by `conan install`. | ||
| If you only ran `conan install` once and didn't specify a build type in the | ||
| first step, it will pick the default one from your Conan profile (usually | ||
| "release"). You can re-run `conan install` with different `build_type` settings | ||
| if you want to be able to easily switch between different build types. | ||
|
|
||
| For **Visual Studio**, enter: | ||
| There are a few options you may want to add to this command to enable or | ||
| disable various features for which we do not have corresponding Conan options. | ||
| The only one we'll mention here is `-DLIBCOSIM_BUILD_TESTS=ON`, which will | ||
| enable running the test suite in step 4. For other options, see the `option()` | ||
| declarations near the top of [CMakeLists.txt], or use the CMake GUI. | ||
|
|
||
| cmake .. -DLIBCOSIM_USING_CONAN=TRUE -A x64 | ||
| ### Step 3: Build libcosim | ||
|
|
||
| For **GCC**, run: | ||
| To build libcosim, now run | ||
|
|
||
| cmake .. -DLIBCOSIM_USING_CONAN=TRUE -DCMAKE_BUILD_TYPE=Debug | ||
| cmake --build --preset=<build-preset-name> | ||
|
|
||
| At this point, we are ready to build and test the software. But first, here are | ||
| some things worth noting about what we just did: | ||
| where `<build-preset-name>` will usually be `conan-release` or `conan-debug`, | ||
| depending again on which build type you want. (Note that on Windows/VS this is | ||
| *different* from the previous step, while on Linux/GCC/Make it must be the | ||
| exact *same*.) | ||
|
|
||
| * The `-A` (architecture) switch we used for Visual Studio ensures that we build | ||
| in 64-bit mode, which is the default for Conan, but not for Visual Studio. | ||
| * In addition to generating build files for MSBuild, CMake generates solution | ||
| files for the Visual Studio IDE. Open the `libcosim.sln` file with VS if you | ||
| want to check it out. | ||
| * For GCC, CMake normally uses a Makefile generator which, unlike Visual | ||
| Studio, is a *single-configuration* generator. Therefore, the choice of | ||
| whether to build in debug or release mode has to be made at generation time, | ||
| using the `CMAKE_BUILD_TYPE` variable. | ||
| ### Step 4 (optional): Run tests | ||
|
|
||
| ### Step 3: Build and test | ||
| If you did not enable unittests in step 2, go back and do so now, and rebuild | ||
| libcosim. Then, run | ||
|
|
||
| When CMake generates IDE project files, as is the case for the Visual Studio | ||
| generator, the software can of course be built, and tests run, from within the | ||
| IDE. Here, however, we will show how to do it from the command line. | ||
| ctest --preset=<build-preset-name> | ||
|
|
||
| The following three commands will build the software, test the software, and | ||
| build the API documentation, respectively: | ||
| where `<build-preset-name>` is the same as in the previous step. | ||
|
|
||
| cmake --build . | ||
| ctest -C Debug | ||
| cmake --build . --target doc | ||
| ### Step 5 (optional): Install libcosim | ||
|
|
||
| (The `-C Debug` switch is only necessary on multi-configuration systems like | ||
| Visual Studio.) | ||
| Before you do this, you probably want to set the [`CMAKE_INSTALL_PREFIX`] | ||
| variable to the desired install location first. Then, simply run: | ||
|
|
||
| All generated files can be found in the directory `build/output`. | ||
| cmake --build --preset=<build-preset-name> --target=install | ||
|
|
||
|
|
||
| [CI without Conan]: ./.github/workflows/ci-cmake.yml | ||
| [CMake]: https://cmake.org | ||
| [`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html | ||
| [CMakeLists.txt]: ./CMakeLists.txt | ||
| [Conan]: https://conan.io | ||
| [Conan CMakeToolchain documentation]: https://docs.conan.io/2/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.html | ||
| [`CONTRIBUTING.md`]: ./CONTRIBUTING.md | ||
| [Cosim]: https://github.com/open-simulation-platform/cosim-cli | ||
| [Cosim Demo Application]: https://github.com/open-simulation-platform/cosim-demo-app | ||
| [cosim4j]: https://github.com/open-simulation-platform/cosim4j | ||
| [Doxygen]: http://www.doxygen.org | ||
| [libcosimc]: https://github.com/open-simulation-platform/libcosimc | ||
| [libcosimpy]: https://github.com/open-simulation-platform/libcosimpy | ||
| [`LICENSE`]: ./LICENSE | ||
| [OSP]: https://opensimulationplatform.com/ | ||
| [proxy-fmu]: https://github.com/open-simulation-platform/proxy-fmu/ | ||
| [Visual Studio]: https://visualstudio.microsoft.com | ||
| [CMake]: https://cmake.org | ||
| [Doxygen]: http://www.doxygen.org | ||
| [Conan]: https://conan.io | ||
| [vcpkg]: https://github.com/Microsoft/vcpkg | ||
| [Conan profile]: https://docs.conan.io/en/latest/using_packages/using_profiles.html | ||
| [cosim]: https://github.com/open-simulation-platform/cosim-cli/blob/master/conanfile.txt | ||
| [Cosim Demo Application]: https://github.com/open-simulation-platform/cosim-demo-app/blob/master/conanfile.txt | ||
| [cosim4j]: https://github.com/open-simulation-platform/cosim4j/blob/master/cosim4j-native/conanfile.txt | ||
| [How to activate the revisions]:https://docs.conan.io/en/latest/versioning/revisions.html?highlight=revisions#how-to-activate-the-revisions |