Adding CPP Terminal to your ptoject

CPP-Terminal is using CMake as it's build system and can therefore be integrated out of the box into projects that are using the same build system. On this page, you will find detailed steps on how to add CPP-Terminal into your project and keep it up to date.

CPP-Terminal switched in late 2021 from just two header files to a full CMake powered library. The library now consists of header files for specific purposes with separate source files. Using source files keeps the externally included code to a minimum and fixes clashes with other libraries (which happened a lot due to the windows header used for native windows functionality).

Using CMake with git sub modules (recommended)

This method uses git to manage the version along with CMake to automatically download and setup CPP-Terminal. Optionally, we can also prefer the locally installed CPP-Terminal version and just dynamically link it and use the git provided version as fallback.

NOTE: This method requires your project to use git.

First we need to add the CPP-Terminal github repository to our project:

git submodule add https://github.com/jupyter-xeus/cpp-terminal

NOTE: More informations on working with git sub modules can be found in it's documentation.

The next step is to configure CMake to download and build CPP-Terminal. As This step is a bit complicated, we have prepared a simple cmake function to get you started immediately:

# TODO

Keeping your version of CPP-Terminal is highly recommended and can be easily automated with tools like dependabot and renovate.

Using CMake only

This method uses only CMake to download and setup CPP-Terminal. It's highly universal and does not require your project to use git, but the update process can't be as easily automated as with the first method. To get you started more quickly, we have prepared a simple cmake function to get you started immediately:

# TODO

Manual setup

Setting up CPP-Terminal by yourself with all of it's header and source files is complicated and should generally be avoided. Also this method makes the update process of your dependencies a lot more time consuming. Copying the cpp-terminal folder in the root directory of this repository as well as adding the .cpp files to your compile target should do the work.

Help

Feel free to ask for help or assistance. We are happy to help you out and assist on getting started with the library.

This section explains how you can use git to automatically download CPP-Terminal, pin it's version to avoid breakage due to updated versions of the library and use CMake to easily build and setup CPP-Terminal to use it.

The basic overview is:

1. Check if CPP-Terminal is locally installed and dynamic link that version (optional)
2. If it's not locally installed, make the git sub module ready
3. use the sub module

add the cpp-terminal repository to your project

NOTE: This requires your project to be inside of an existing git repository. Refer to the next option for a git independent approach.

In this step, you are adding CPP-Terminal as sub module to your git repository.

git submodule add https://github.com/jupyter-xeus/cpp-terminal

This will clone CPP-Terminal into your repository and creates the submodule configuration files needed by git.

NOTE: Use git submodule --help to show all available options. NOTE: We recommend to setup dependabot or renovate in order to keep CPP-Terminal up to date.

configure CMake to use the locally installed version of CPP-Terminal first (recommended)

In this step, we will configure CMake to use the locally installed version of CPP-Terminal if it exists.

To make this guide as easy as possible, we have created a function for CMake to set it up:

// TODO

configure CMake to just use the git sub module

Nor using the locally installed version can be preferred, if you don't want users or packagers to be able to dynamically link cpp-terminal. This is not recommended, but might be preferable in some use cases.

// TODO

Using CMake alone

This method uses CMake to download the GitHub repository of CPP-Terminal and set it up. Only using CMake makes the Project more portable between different development environments and version controls, but requires you to manually maintain the used version of the library, instead of letting it being handled by automation.

NOTE: Not updating CPP-Terminal over a long period of time is highly dangerous and not recommended. Please keep your dependencies up to date.

// TODO

Manually Copying the files over

This Method is the by far most complicated option and requires you to copy the files over and add them to your build system. This should only be done, if your project is not using CMake, or if you know what you are doing.

NOTE: Not updating CPP-Terminal over a long period of time is highly dangerous and not recommended. Please keep your dependencies up to date.

Other build systems

You are using another build system in your project? Feel free to add a small how-to to this list. Your contribution is really appreciated and welcome!