Skip to content

Latest commit

 

History

History
executable file
·
300 lines (238 loc) · 13.2 KB

contributing-clion.md

File metadata and controls

executable file
·
300 lines (238 loc) · 13.2 KB
Raw

Introduction

In this tutorial, we will go through the steps necessary to contribute to Elektra to make it easier for you to get started. We will use a Unix based OS like Linux and CLion for development, but depending on where you want to contribute code, other IDEs will also be sufficient. Before you start, please read this to get familiar with the process of contributing to Elektra.

Prerequisites

Forking the Repository

Libelektra is hosted on GitHub. You can find its repository here:

To be able to make pull requests, you need a copy of this repository inside your GitHub account. You can find a tutorial about how to do this here (remember to sign into your account first). After this, you should see this copy in the list of your own repositories with a hint of it's origin.

Getting the Code

To develop for libelektra, we now have to "download" your copy of its original repository. In git this process is called "cloning". CLion has built-in Git support which we will use for this tutorial. Once you have opened CLion click on:

Check out from Version Control --> Git

and paste the URL of your forked libelektra-repository inside the URL field. Then choose the directory you want to store your project in. To be also able to directly push changes back to your repository, we'll also configure CLion to be able to use your GitHub account. Click on the "Log in to GitHub" button and enter your GitHub credentials and confirm. The last step here is to click "Clone" to download the project and open it in CLion.

Alternatively you can also clone your repository using the command line. Open a terminal and navigate to the folder you want to save the source code into and type:

git clone https://github.com/ElektraInitiative/libelektra.git

With the project now locally available we can start developing.

Setting Up the Project

To import all of the project's configuration, open CMakeLists.txt inside the project's root directory and click on "Load CMake project" which will appear on the top right corner of the source view.

If you've cloned the project using a terminal. start CLion and once you see the main menu, click "Open" and select the CMakeLists.txt file inside the project's root directory. This will import the project accordingly and populate you run configuration with some predefined values. In rare occurrences this won't happen. If that is the case for you, simply restart CLion using:

File --> Invalidate Caches / Restart... --> Invalidate and Restart

Now after all processes of CLion have finished, the project should be set up and the run configuration should be populated with entries.

Since some kdb-operations require root access and it is not recommended to start programs (like CLion) with root access if they usually don't require it, we have to change our CMake configurations to get rid of this requirement. To do that, open:

File --> Settings --> Build, Execution, Deployment --> CMake

There you can edit your CMake profiles. To get rid of the root requirement we'll add the following CMake options to our "Debug" profile:

-DKDB_DB_SYSTEM="~/.config/kdb/[xyz]/system"
-DKDB_DB_SPEC="~/.config/kdb/[xyz]/spec"
-DKDB_DB_USER=".config/kdb/[xyz]/user"
-DCMAKE_INSTALL_PREFIX=install
-DINSTALL_SYSTEM_FILES=OFF

where "[xyz]" can be replaced by any unique identifier so that different profiles won't clash with each other. This configuration also isolates your build of Elektra from any existing Elektra installation on your system. For debugging purposes we also recommend to add the following CMake options for debug builds to enable further logging and checks:

-DENABLE_DEBUG=ON
-DENABLE_LOGGER=ON

To increase the build speed you can also change the "Build option" to e.g.

-j 8

which, in this case, starts 8 build jobs in parallel. For optimal performance this value should represent the number of available cores of your CPU + few extra jobs.

It remains to be noted that CLion maintains all CMake profiles in parallel. If some CMake file changes, CLion executes cmake for each profile which can put a lot of strain on your system.

Finally check if ClangFormat is enabled for the project to automatically adhere to the formatting guidelines of the project when formatting the code. You can find the settings here:

File --> Settings... --> Editor --> Code Style

Make sure the selected "Scheme" is "Project".

Development

Usually the folders you have to work in to add functionality or documentation are as follows:

  • doc
    This folder contains mainly all documentation of the project, including almost all pages of the homepage of this project. One important note is, that all Markdown-pages can also be used for testing using Markdown to Shell Recorder (you can find an example on how to do this here).
  • src
    Almost all functionality-code resides here.
    • bindings
      Here is all the code of available Bindings of libelektra.
    • plugins
      You can find all developed Plugins here. If you want to fix a bug for an existing plugin or add another one, this is the directory you have to work in. For further information on how to develop your own plugin, please visit this tutorial.
    • tools
      In this folder the source of all tools for interacting with Elektra's global key database, e.g. kdb, can be found.
  • tests
    Here you can find all sorts of tests (excluding tests created with the Markdown to Shell Recorder-tool).

Testing

The most thorough way to test your changes is to run all tests. Therefore navigate to your run-configurations (Run -> Edit Configurations...) and look for the entry run_all. There, run_all should be selected as Executable, kdb as Target. Now you can execute this run configuration which will run all enabled tests! Alternatively you can also run all tests using the terminal by executing make run_all inside your build folder (e.g. /cmake-build-debug).

You can also run other specific tests by settingTarget and Executable to any of the testmod_* or testkdb_*targets. Additionally all tests using Google Test (e.g. tests/kdb/*) can be run directly using CLion by opening their source code and clicking on the green icon next to the class name.

If you want to test various kdb methods separately, you can create your own run configurations. Add a new one by clicking on the "+"-sign on the top left of the "Edit Configurations..." dialog and name it. Here both Executable and Target should have "kdb" selected. If you for example want to test kdb info dump, write "info dump" next to Program arguments. That's it, now you can just test this part of kdb.

For further information please read this.

Commiting Your Changes

Once you are satisfied with your changes, you have to commit them to your forked repository. We'll use the terminal for working with git. By convention, such commits shouldn't be too large, otherwise it will become difficult to revert some small changes if they are not working as intended. If you use the terminal for your Git operations, to be able to commit code to your repository, you have to configure your local Git installation to use your GitHub credentials. You can find information about how to do this here. After you've set up your Git configuration, you can continue with uploading your changes.

By default, you are in the "master" branch of your repository. First, you should never directly work on the master branch, since only working code is expected to be there. This means, we now create a branch in our repository where our code changes will be published into. On the bottom right of your CLion window you can find the button "Git: ". Click it and select "+ New Branch". Type in the name of your new branch (e.g. "testbranch") and keep "Checkout branch" checked to automatically switch to it as your working branch.

Alternatively open a terminal, navigate to the root directory of your local code and type:

git branch testbranch
git checkout testbranch

After you have changed some files it is time to publish them to your repository. To do that, open:

VCS --> Commit...

In the dialog you have opened you can now select the files you want to include in your commit. The first line should have the following syntax:

module: short statement

If you fixed a bug in kdb cp the first line of your commit message could be KDB: Fixed cp not copying value. Your commit message should also include a reference to the issue you have fixed so that the issue can be closed automatically once your code change gets included to the official repository (e.g. Closes #1234). Before committing your changes please make sure that "Reformat code" and "Rearrange code" are disabled in the commit dialog. Otherwise Clions formatter might produce files that don't adhere to our formatting guidelines. If you installed the pre-commit-check-formatting pre-commit-hook from the scripts directory. Ensure that "Run Git hooks" is enabled in the commit dialog. Finally you can commit your changes by clicking the "Commit" button and navigate to:

VCS --> Git --> Push

To do that in one step, you can also click on the arrow next to the "Commit" button and directly choose "Commit and Push...".

Using the terminal you first have to add all files you've changed and also want in your commit to the stage. Suppose we've changed how kdb cp works, we now have to add it to our files we want to commit (you can add several files for a commit too):

git add ./src/tools/kdb/cp.cpp

Now we've staged our modified file for our commit. The final step is to actually commit it to your online repository. Therefore type:

git commit -m "<commit message>"
git push origin testbranch

With this, you've published your changes to your remote branch of your repository. The next step is merging this change into the original repository.

Creating a Pull Request

This step is most easily done using a browser. Open the web page of the Git repository of libelektra (https://github.com/ElektraInitiative/libelektra) and log in to your account if have not already done so. Navigate to "Pull requests", there you can find a green button called "New pull request". By clicking it (shortcut), you can now create a pull request referencing your forked repository and the branch,the modified code resides in. Click on "compare across forks" so that you can find and select your branch. Choose "/libelektra" as the head repository and "testbranch" as the compare-branch. Now the green button "Create pull requests" should be enabled. By clicking it you can define the title of your pull request and write a description of the work you have done. Please read the template in this form and include the information stated there if possible. Finally by clicking "Create pull request" you've successfully created a pull request to merge your changes into the official repository! Now maintainers of libelektra will review your code and, if everything is fine, merge your changes into the official repository. Otherwise they'll comment on this pull request if further changes are needed. To include additional changes in this pull request, just commit new code changes to the same repository and branch you've referenced for this pull request, they will be added automatically to it. In any case check the output of the automated tests!

If you want to use CLion for creating Pull Request, please check out this link for further information.

Hints

  • Especially for not that well-versed programmers don't forget that when debugging e.g. KeySet, which can contain many Key objects, you can only see that there may be more than one key stored in this set by it's size attribute since it's keys are referenced by a pointer. Just the first Key (referenced by the pointer) will be visible directly using the debugger. To analyse it's stored Key objects you can either add a watch or use the GDB debug console (next to the "variables" tab inside the debugger view).
  • Sometimes CLion does not rebuild changed modules accordingly by just running the test. If you think, that the modules should have been rebuilt (e.g. if running testmod_abc doesn't rebuild abc), please report the issue under https://issues.libelektra.org, so we can fix the CMake dependencies. As temporary fix you can try to rebuild the project and restart the test.
  • Please add a line of changelog to this file and add it to your pull request, otherwise some test will fail in any case.