Guidelines and HOWTOs/Build from source/edk: Difference between revisions

From KDE Community Wiki
(config.ini is now optional)
(Document the new -e switch)
Line 61: Line 61:
   edk r
   edk r


This will execute whatever is defined in the <code>project</code> key, unless you define an <code>executable</code> key in the <code>[project]</code> section.
This will execute whatever is defined in the <code>project</code> key, unless you define an <code>executable</code> key in the <code>[project]</code> section. You can override both with the <code>-e</code> switch:


If you want to pass arguments to the project:
    edk r -e autotests/footest
 
will run the <tt>autotests/footest</tt> executable located in your build directory.
 
If you want to pass arguments to the executable:


   edk r --foo --bar=XXX
   edk r --foo --bar=XXX

Revision as of 15:15, 14 August 2016

edk is a Python script that can be used to easily build KDE projects. Once edk is properly installed and configured, building any KDE project is as easy as invoking edk from the git root of the project.

Motivations

You may be interested in edk if:

  • You are a new contributor looking for a simple development environment
  • You are a new contributor and you want to build just one application
  • You want to build KDE projects on top of an existing Plasma environment
  • You want to build KDE projects on top of a third party environment (e.g. Gnome or Unity)
  • You are tired to manually call cmake, make, make test, ...

How does it work?

edk is designed to just build, install and (optionally) "run" your project (as edk is primarily designed for applications with a single executable). You don't need to worry about setting up a development environment (besides installing edk itself).

edk is not a replacement of kdesrc-build. It doesn't download source code and it doesn't resolve dependencies (in fact, edk assumes that all build-dependencies are already satisfied). If you want to build the whole KDE stack, kdesrc-build is still the way to go.

Installation

git clone git://anongit.kde.org/scratch/elvisangelaccio/edk.git
# assuming that $HOME/bin is in your $PATH
ln -s $PWD/edk/edk.py $HOME/bin/edk
# optional, if you want to customize your build settings or environment variables
mkdir ~/.config/edk
cp edk/config.ini.example ~/.config/edk/config.ini
cp edk/env.sh.example ~/config/edk/env.sh

Note

You can replace ~/.config with $XDG_CONFIG_HOME, if you have this variable set


Usage

Build a project

From the git root of the project:

 edk

This is a shorthand for edk b with no additional arguments. The script will perform the following operations:

  • If $XDG_CONFIG_HOME/edk/env.sh exists, it will source whatever environment variables are exported in there.
  • Build the CMake-based project found in $(pwd). Build files are written to a subdirectory of $XDG_CACHE_HOME/edk.
  • Install the project in $EDK. This variable defaults to $XDG_DATA_HOME/edk, but you can override it in env.sh.
  • Run the project tests (if available).

Configure the project

edk will respect the options defined in the [project] section of the config file. The value of the project key is defined in the following order:

  1. The value of the -p switch, for example edk -p foo
  2. The value of the project key in the [global] section of the config file
  3. The name of the directory edk was run from.

The value of this key is also used as the name of the build directory in $XDG_CACHE_HOME/edk.

Run the project

Once the project is built, you can run it with:

 edk r

This will execute whatever is defined in the project key, unless you define an executable key in the [project] section. You can override both with the -e switch:

   edk r -e autotests/footest

will run the autotests/footest executable located in your build directory.

If you want to pass arguments to the executable:

 edk r --foo --bar=XXX

Debug the project

Similarly to the r subcommand, it's also possible to run the project with a debugger (only gdb for now):

 edk d

This will execute gdb <executable>.

Clean build

 edk b -c

This will delete the build directory before performing a new build.

Configuration

Build with Ninja

Add -GNinja in the cmake-options of your config.ini file (either in the [global] section on in a project-specific section).