Difference between revisions of "Hacking:Building"

From GIMP Developer Wiki
Jump to: navigation, search
(Update with instructions that cover the latest build, including a warning about $XDG_DATA_DIRS. Add a link to Hacking:Problems_and_solutions.)
(Remove the line about needing gegl branch gegl-0-4 for gimp 2.10: it's not true and it doesn't exist anyway.)
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This page contains things that you should know in order to build GIMP.
 
This page contains things that you should know in order to build GIMP.
 
__TOC__
 
__TOC__
 +
 +
== Prerequisites ==
 +
* You should know roughly how to use a terminal and the command line.
 +
* You should know roughly what are environment variables.
 +
  
 
== GIMP's dependencies ==
 
== GIMP's dependencies ==
Line 15: Line 20:
 
* [[Wikipedia:GEGL#babl|babl]] – a library for converting between pixel formats, heavily used by GIMP when communicating with GEGL.  
 
* [[Wikipedia:GEGL#babl|babl]] – a library for converting between pixel formats, heavily used by GIMP when communicating with GEGL.  
 
* [[Wikipedia:GEGL|GEGL]] – a graph based image processing library, heavily used in GIMP’s core.
 
* [[Wikipedia:GEGL|GEGL]] – a graph based image processing library, heavily used in GIMP’s core.
:To build GIMP 2.10, you need the GEGL version from git branch 'gegl-0-4'.
 
:To build GIMP master (= the development version of GIMP), you need the GEGL version from git branch 'master'.
 
  
 
Some of GIMP's plugins depend on (at least) the following libraries
 
Some of GIMP's plugins depend on (at least) the following libraries
Line 31: Line 34:
  
 
== Build system ==
 
== Build system ==
=== Building from a Tarball vs. building from latest source (Git) ===
 
There are two ways to get the source. Releases are usually packaged in a tar archive or "tarball", which will usually have an extension like .tar, .tar.gz, tar.bz2. You can download tarballs from:
 
<pre>http://download.gimp.org/pub/babl/
 
http://download.gimp.org/pub/gegl/
 
http://download.gimp.org/pub/gimp/
 
</pre>
 
 
You can also check out the source using the version control system Git. This is the only way to get the most up-to-date development release, but you can also see older releases (using branches). Building from git is slightly different from building from a tarball.
 
  
 
== Preparing for Building ==
 
== Preparing for Building ==
Line 49: Line 44:
 
<b>1. Choose a place to install everything, and set a variable to point to it:</b>
 
<b>1. Choose a place to install everything, and set a variable to point to it:</b>
  
<pre>
+
If you're building Gimp from master, you may not want to install it in your system prefix, as you may break your system Gimp installation, or get odd behavior, especially if you also have a system version of GIMP installed.
export INSTALL_PREFIX=$HOME/gimp-git
+
</pre>
+
  
It's <b>very important</b> that you choose an install prefix, and not just let it install to /usr/local or wherever! If you do that, you will probably see odd behavior, especially if you also have a system version of GIMP installed.
+
You should then create another prefix directory where Gimp (and some dependencies) may be installed safely. On Linux you could use $HOME/.local. Let's name your custom prefix :
  
<b>2. Create that directory, and a "share" subdirectory:</b>
+
GIMP_PREFIX=${HOME}/gimp_prefix
 
+
<pre>
+
mkdir -p $INSTALL_PREFIX/share
+
</pre>
+
  
 
<b>3. Set some environment variables:</b>
 
<b>3. Set some environment variables:</b>
  
Here's an example of setting environment variables for the build, though the exact values will vary according to your OS, distro and other factors (Linux users, see the Linux build page [[Hacking:Building/Linux]] for some examples). You may need to run meson and autogen.sh/configure several times to nail them all down.
+
Some dependencies may be installed in this prefix too, so the build system should be able to find them :
<pre>
+
export PATH="$INSTALL_PREFIX/bin:$PATH"
+
export PKG_CONFIG_PATH="$INSTALL_PREFIX/lib/pkgconfig:$INSTALL_PREFIX/share/pkgconfig:$PKG_CONFIG_PATH"
+
export LD_LIBRARY_PATH="$INSTALL_PREFIX/lib:$LD_LIBRARY_PATH"
+
export ACLOCAL_FLAGS="-I $INSTALL_PREFIX/share/aclocal $ACLOCAL_FLAGS"
+
</pre>
+
  
GIMP build used to look for a file named $INSTALL_PREFIX/share/config.site and run it automatically, so many people used that as a place to define their environment variables. Now, with meson builds, <b>config.site is no longer run automatically</b>, so you'll have to do that step by hand.
+
# Used to find programs/tools during build
 +
export PATH="${GIMP_PREFIX}/bin:$PATH"
 +
 +
# Used to detect the build dependencies
 +
export PKG_CONFIG_PATH="${GIMP_PREFIX}/lib/pkgconfig:${GIMP_PREFIX}/share/pkgconfig"
 +
 +
# Used to find the glib-introspection dependencies
 +
export XDG_DATA_DIRS="${GIMP_PREFIX}/share:/usr/share:$XDG_DATA_DIRS"
 +
 +
# Used to find the libraries at runtime
 +
export LD_LIBRARY_PATH="${GIMP_PREFIX}/lib:${LD_LIBRARY_PATH}"
 +
 +
# Used by Autotools to find its tools
 +
export ACLOCAL_FLAGS="-I $INSTALL_PREFIX/share/aclocal $ACLOCAL_FLAGS"
  
You may see examples that also set the variable XDG_DATA_DIRS. <b>Don't.</b> Doing so will confuse gdk-pixbuf and may lead to build failures with messages like "Couldn't recognize the image file format".
+
Note: if you don't include the default value of XDG_DATA_DIRS, you may get a compile error trying to read a PNG icon file. You could try using this in that case:
 +
export XDG_DATA_DIRS="${GIMP_PREFIX}/share:/usr/local/share:/usr/share"
  
== Check Out the Source ==
+
'''For Debian or derivatives (Ubuntu, Mint…) only:'''
  
Clone from git:
+
Additionally to the previous commands (not in replacement), update some variables this way if you use a Debian derivative:
<pre>
+
  arch="$(dpkg-architecture -qDEB_HOST_MULTIARCH 2> /dev/null)"
git clone https://gitlab.gnome.org/GNOME/babl.git
+
  export PKG_CONFIG_PATH="${GIMP_PREFIX}/lib/${arch}/pkgconfig:$PKG_CONFIG_PATH"
git clone https://gitlab.gnome.org/GNOME/gegl.git
+
  export LD_LIBRARY_PATH="${GIMP_PREFIX}/lib/${arch}:$LD_LIBRARY_PATH"
git clone https://gitlab.gnome.org/GNOME/gimp.git
+
</pre>
+
  
Or get tarballs from:
+
== Download the source code ==
<pre>
+
http://download.gimp.org/pub/babl/
+
http://download.gimp.org/pub/gegl/
+
http://download.gimp.org/pub/gimp/
+
</pre>
+
  
=== Additional Git Requirements ===
+
=== Download with git ===
  
To Build Git Master, You Also Need:
+
This is preferred when working on the source code and developing Gimp.
<pre>
+
git clone https://github.com/mypaint/mypaint-brushes.git
+
git clone https://github.com/mypaint/libmypaint.git
+
</pre>
+
  
== Build libmypaint and mypaint-brushes ==
+
git clone https://gitlab.gnome.org/GNOME/babl.git
 +
git clone https://gitlab.gnome.org/GNOME/gegl.git
 +
git clone https://gitlab.gnome.org/GNOME/gimp.git
  
cd into the directory where you unpacked libmypaint. Make sure you have
+
You can build specific versions by choosing a ''tag'' (a fixed git revision)…
the *libmypaint-v1* branch checked out:
+
# List available tags
 +
git tag
 +
# Update the working directory to a specific tag :
 +
git checkout GIMP_2_10_12
  
If you're building source you checked out from git, run:
+
… or a ''branch'' :
 +
# List available branches
 +
git branch -a
 +
# Checkout a branch :
 +
git checkout
 +
git checkout -b wip/animation
  
<pre>
 
./autogen.sh
 
</pre>
 
  
This generates a configure script. If you're building from a tarball, you should already have a configure script and can skip that step.
+
If your distro does not provide them, you should get the Mypaint libs too :
  
If you think you might want to set any special options, you can now run ```./configure --help``` to see what's available.
+
git clone --branch libmypaint-v1 https://github.com/mypaint/libmypaint.git
 +
git clone --branch v1.3.x https://github.com/mypaint/mypaint-brushes.git
  
Then:
+
=== Download release archives ===
<pre>
+
./configure --prefix=INSTALL_PREFIX
+
</pre>
+
  
Check the output to make sure you aren't missing any features you might want.
+
Gimp also provides release archives. This is preferred when building stable releases.
Then:
+
  
<pre>
+
https://download.gimp.org/pub/babl
make && make install
+
https://download.gimp.org/pub/gegl
</pre>
+
https://download.gimp.org/pub/gimp
  
Then repeat for mypaint-brushes.
+
Releases for mypaint can be found on their github page.
  
== Build babl and gegl ==
+
== Build the source code ==
  
Babl and gegl now use meson/ninja as their build system. Build babl this way:
+
=== Mypaint ===
  
<pre>
+
For both Libmypaint '''''and Mypaint-brushes''''', use Autotools to install :
cd babl
+
 
SRCDIR=$(pwd)
+
cd libmypaint
BUILD_DIR=$SRCDIR/obj-$(arch)
+
mkdir -p $BUILD_DIR
+
# Generate the configure script. That may be unnecessary with release archives :
cd $BUILD_DIR
+
# If you might want to set special options, you can now run `./configure --help` to see what's available.
meson -Dprefix=$INSTALL_PREFIX $SRCDIR && ninja && ninja install
+
./autogen.sh
</pre>
+
 +
# Configure the build (you can call ./configure --help):
 +
./configure --prefix=${GIMP_PREFIX}
 +
 +
# Build the code :
 +
make -j$(nproc) install
 +
 +
cd ..
 +
 
 +
=== BABL and GEGL ===
 +
 
 +
Babl and Gegl use Meson. The build needs to be out-of-source, but the process is simple.
 +
 
 +
You can read the file meson_options.txt to find a list of options.
 +
 
 +
You may enable Link-time optimization (meson option <code>b_lto</code>)to have better performance.
 +
 
 +
cd babl
 +
meson _build \
 +
    --prefix=${GIMP_PREFIX} \
 +
    --buildtype=release \
 +
    -Db_lto=true
 +
 +
cd _build
 +
ninja
 +
ninja install
  
 
Then repeat for gegl.
 
Then repeat for gegl.
  
== Build gimp ==
+
=== Gimp ===
 +
 
 +
Finally, you're ready to build Gimp!
 +
 
 +
You can choose between Autotools and Meson.
 +
 
 +
Meson is much faster than Autotools, but newer so considered "beta" quality.
 +
 
 +
==== Autotools build ====
  
Finally, you're ready to build gimp! The steps are similar to that for libmypaint, except that ./autogen.sh runs ./configure for you.
+
The steps are similar to that for libmypaint, except that ./autogen.sh runs ./configure for you.
  
 
cd into the directory where you unpacked gegl.
 
cd into the directory where you unpacked gegl.
Line 151: Line 174:
 
If you're building source you checked out from git, run:
 
If you're building source you checked out from git, run:
  
<pre>
+
./autogen.sh --prefix=INSTALL_PREFIX
./autogen.sh --prefix=INSTALL_PREFIX
+
</pre>
+
  
 
This generates a configure script and then runs it.
 
This generates a configure script and then runs it.
  
 
If you're building from a tarball, use configure instead of autogen:
 
If you're building from a tarball, use configure instead of autogen:
<pre>
+
 
./configure --prefix=INSTALL_PREFIX
+
./configure --prefix=INSTALL_PREFIX
</pre>
+
  
 
You can run ```./configure --help``` if you want to see special options you can configure.
 
You can run ```./configure --help``` if you want to see special options you can configure.
Line 167: Line 187:
 
Then:
 
Then:
  
<pre>
+
make && make install
make && make install
+
 
</pre>
+
==== Meson build ====
 +
 
 +
Numerous options are available to configure the build.
 +
 
 +
You should read the file <code>meson_options.txt</code> to know the options specific to this project.
 +
Meson also provides some useful options, such as :
 +
 
 +
* <code>warning_level=[1, 2, 3]</code> : The level of compiler warnings
 +
* <code>b_lto=true|false</code> : Enable link-time optimizations
 +
* <code>b_coverage=true|false</code> : Enable coverage tools.
 +
* <code>b_pgo=off|generate|use</code> : Enable profile guided optimizations
 +
* <code>b_sanitize=none|address|thread|undefined|memory|address,undefined</code> : Use a code sanitizer
 +
 
 +
 
 +
cd gimp
 +
meson _build \
 +
    --prefix=${GIMP_PREFIX} \
 +
    --buildtype=release \
 +
    -Djavascript=always \
 +
    -Dlua=always \
 +
    -Dpython=always
 +
 +
cd _build
 +
ninja
 +
ninja install
 +
 
 +
==== Useful build options ====
 +
 
 +
You can customize the Gimp settings directory. This prevents any interference with other GIMP installations on the same computer.
  
Repeat the same steps for gimp.
+
* Autotools build : <code>--with-gimpdir=GIMP/git-master</code>
 +
* Meson build : <code>-Dgimpdir=GIMP/git-master</code>
  
 
== Problems? ==
 
== Problems? ==
Line 181: Line 230:
 
== Running Your New GIMP ==
 
== Running Your New GIMP ==
  
You will probably need to set some environment variables in order to run the gimp you just built. In addition to the variables you used for the build, you may need
+
You need to keep defined the same environment variables as for the build. You may want to define them in a script that you will source with :
<pre>
+
 
export XDG_DATA_DIRS=$GIMP_PREFIX/share:$XDG_DATA_DIRS
+
source ~/gimp_definitions.sh
</pre>
+
 
 +
To keep those variables contained only for the execution of Gimp, you may want to use subshells :
 +
 
 +
(source ~/gimp_definitions.sh ; $GIMP_PREFIX/bin/gimp-2.10)
 +
 
  
 
See the OS-specific pages for more specific advice:
 
See the OS-specific pages for more specific advice:
Line 191: Line 244:
 
* [[Hacking: Building/Mac OSX]] - Building GIMP on the Mac platform
 
* [[Hacking: Building/Mac OSX]] - Building GIMP on the Mac platform
 
* [[Hacking:Building/Windows]] - Building GIMP on Windows
 
* [[Hacking:Building/Windows]] - Building GIMP on Windows
 +
 +
 +
== Build the web Gimp documentation ==
 +
You can also build the documentation website (https://www.gimp.org/docs).
 +
 +
It uses <code>docbook</code> that requires some softwares, such as:
 +
gettext
 +
automake
 +
docbook2odf
 +
pngcrush
 +
pngnq
 +
docbook-xsl
 +
docbook-utils
 +
dblatex
 +
 +
 +
Now, to build the documentation:
 +
 +
git clone --depth=0 git@gitlab.gnome.org:GNOME/gimp-help.git
 +
cd gimp-help
 +
# Set this variable to your own language. It should correspond to a directory in the "po" source folder.
 +
export LINGUAS=en
 +
./autogen.sh [--without-gimp ALL_LINGUAS="en"]
 +
make
 +
make pdf-local

Latest revision as of 00:08, 23 March 2020

This page contains things that you should know in order to build GIMP.

Prerequisites

  • You should know roughly how to use a terminal and the command line.
  • You should know roughly what are environment variables.


GIMP's dependencies

Gimp depends on quite a few libraries, including but not limited to:

  • GLib – a library used by many gnome applications, containing utilities and common data structures for programs written in C.
  • GObject - a library for implemnting objects (as in Object-Oriented-Programming) in C.
  • GTK+ – a graphical toolkit for building cross-platform user interfaces. GIMP 2.99 and later need GTK 3.0.
  • Cairo – a 2D graphics library, used for drawing some of GIMP’s widget and also used by Gtk+.
  • Python-Cairo: Python bindings for Cairo
  • Pango – a library for laying out and rendering text, used also in Gtk+.
  • MyPaint - a painting library that allows a lot of flexibility for brushes; it needs both libmypaint (the libmypaint-v1 branch) and mypaint-brushes (the v1.3.x branch).

GIMP's core depends also on two libraries which are mainly (but not only) intended to be used with GIMP:

  • babl – a library for converting between pixel formats, heavily used by GIMP when communicating with GEGL.
  • GEGL – a graph based image processing library, heavily used in GIMP’s core.

Some of GIMP's plugins depend on (at least) the following libraries

  • librsvg – a library for rendering SVG files.
  • libpng – a library for reading and writing PNG image files. Used by Gtk+, GIMP and GEGL.
  • libexif - a library for manipulating exif data (image metadata).
  • libwmf - a library for working with WMF files.
  • libtiff - a library for reading and writing TIFF image files.
  • libjpeg - a library for reading and writing JPEG image files.
  • liblcms - the Little Color Management System, a library for working with color profiles.

This list is incomplete.

See also the file INSTALL (or INSTALL.in in GIMP master).

Build system

Preparing for Building

You may need to install some software to build GIMP, including a C compiler, make, GNU autotools, meson, and more, plus many dependencies. See the OS-specific pages for details:

1. Choose a place to install everything, and set a variable to point to it:

If you're building Gimp from master, you may not want to install it in your system prefix, as you may break your system Gimp installation, or get odd behavior, especially if you also have a system version of GIMP installed.

You should then create another prefix directory where Gimp (and some dependencies) may be installed safely. On Linux you could use $HOME/.local. Let's name your custom prefix :

GIMP_PREFIX=${HOME}/gimp_prefix

3. Set some environment variables:

Some dependencies may be installed in this prefix too, so the build system should be able to find them :

# Used to find programs/tools during build
export PATH="${GIMP_PREFIX}/bin:$PATH"

# Used to detect the build dependencies
export PKG_CONFIG_PATH="${GIMP_PREFIX}/lib/pkgconfig:${GIMP_PREFIX}/share/pkgconfig"

# Used to find the glib-introspection dependencies
export XDG_DATA_DIRS="${GIMP_PREFIX}/share:/usr/share:$XDG_DATA_DIRS"

# Used to find the libraries at runtime
export LD_LIBRARY_PATH="${GIMP_PREFIX}/lib:${LD_LIBRARY_PATH}"

# Used by Autotools to find its tools
export ACLOCAL_FLAGS="-I $INSTALL_PREFIX/share/aclocal $ACLOCAL_FLAGS"

Note: if you don't include the default value of XDG_DATA_DIRS, you may get a compile error trying to read a PNG icon file. You could try using this in that case:

export XDG_DATA_DIRS="${GIMP_PREFIX}/share:/usr/local/share:/usr/share"

For Debian or derivatives (Ubuntu, Mint…) only:

Additionally to the previous commands (not in replacement), update some variables this way if you use a Debian derivative:

 arch="$(dpkg-architecture -qDEB_HOST_MULTIARCH 2> /dev/null)"
 export PKG_CONFIG_PATH="${GIMP_PREFIX}/lib/${arch}/pkgconfig:$PKG_CONFIG_PATH"
 export LD_LIBRARY_PATH="${GIMP_PREFIX}/lib/${arch}:$LD_LIBRARY_PATH"

Download the source code

Download with git

This is preferred when working on the source code and developing Gimp.

git clone https://gitlab.gnome.org/GNOME/babl.git
git clone https://gitlab.gnome.org/GNOME/gegl.git
git clone https://gitlab.gnome.org/GNOME/gimp.git

You can build specific versions by choosing a tag (a fixed git revision)…

# List available tags
git tag
# Update the working directory to a specific tag :
git checkout GIMP_2_10_12

… or a branch :

# List available branches
git branch -a
# Checkout a branch :
git checkout 
git checkout -b wip/animation


If your distro does not provide them, you should get the Mypaint libs too :

git clone --branch libmypaint-v1 https://github.com/mypaint/libmypaint.git
git clone --branch v1.3.x https://github.com/mypaint/mypaint-brushes.git

Download release archives

Gimp also provides release archives. This is preferred when building stable releases.

https://download.gimp.org/pub/babl
https://download.gimp.org/pub/gegl
https://download.gimp.org/pub/gimp

Releases for mypaint can be found on their github page.

Build the source code

Mypaint

For both Libmypaint and Mypaint-brushes, use Autotools to install :

cd libmypaint

# Generate the configure script. That may be unnecessary with release archives :
# If you might want to set special options, you can now run `./configure --help` to see what's available.
./autogen.sh

# Configure the build (you can call ./configure --help):
./configure --prefix=${GIMP_PREFIX}

# Build the code :
make -j$(nproc) install

cd ..

BABL and GEGL

Babl and Gegl use Meson. The build needs to be out-of-source, but the process is simple.

You can read the file meson_options.txt to find a list of options.

You may enable Link-time optimization (meson option b_lto)to have better performance.

cd babl
meson _build \
    --prefix=${GIMP_PREFIX} \
    --buildtype=release \
    -Db_lto=true

cd _build
ninja
ninja install

Then repeat for gegl.

Gimp

Finally, you're ready to build Gimp!

You can choose between Autotools and Meson.

Meson is much faster than Autotools, but newer so considered "beta" quality.

Autotools build

The steps are similar to that for libmypaint, except that ./autogen.sh runs ./configure for you.

cd into the directory where you unpacked gegl.

If you're building source you checked out from git, run:

./autogen.sh --prefix=INSTALL_PREFIX

This generates a configure script and then runs it.

If you're building from a tarball, use configure instead of autogen:

./configure --prefix=INSTALL_PREFIX

You can run ```./configure --help``` if you want to see special options you can configure.

Check the output to make sure you aren't missing any features you might want. Then:

make && make install

Meson build

Numerous options are available to configure the build.

You should read the file meson_options.txt to know the options specific to this project. Meson also provides some useful options, such as :

  • warning_level=[1, 2, 3] : The level of compiler warnings
  • b_lto=true|false : Enable link-time optimizations
  • b_coverage=true|false : Enable coverage tools.
  • b_pgo=off|generate|use : Enable profile guided optimizations
  • b_sanitize=none|address|thread|undefined|memory|address,undefined : Use a code sanitizer


cd gimp
meson _build \
    --prefix=${GIMP_PREFIX} \
    --buildtype=release \
    -Djavascript=always \
    -Dlua=always \
    -Dpython=always

cd _build
ninja
ninja install

Useful build options

You can customize the Gimp settings directory. This prevents any interference with other GIMP installations on the same computer.

  • Autotools build : --with-gimpdir=GIMP/git-master
  • Meson build : -Dgimpdir=GIMP/git-master

Problems?

Most problems will occur during the configure stage, and with any luck it's just a missing package and the error message will make it clear what package you need. But there are more subtle problems that can occur. If you have a difficult error, look in:

Hacking:Problems_and_solutions

Running Your New GIMP

You need to keep defined the same environment variables as for the build. You may want to define them in a script that you will source with :

source ~/gimp_definitions.sh

To keep those variables contained only for the execution of Gimp, you may want to use subshells :

(source ~/gimp_definitions.sh ; $GIMP_PREFIX/bin/gimp-2.10)


See the OS-specific pages for more specific advice:


Build the web Gimp documentation

You can also build the documentation website (https://www.gimp.org/docs).

It uses docbook that requires some softwares, such as:

gettext
automake
docbook2odf
pngcrush
pngnq
docbook-xsl 
docbook-utils
dblatex


Now, to build the documentation:

git clone --depth=0 git@gitlab.gnome.org:GNOME/gimp-help.git
cd gimp-help
# Set this variable to your own language. It should correspond to a directory in the "po" source folder.
export LINGUAS=en
./autogen.sh [--without-gimp ALL_LINGUAS="en"]
make
make pdf-local