Inkscape Wiki - User contributions [en]

CMake

2016-05-11T09:21:42Z

Objarni: /* Using CMake to build Inkscape */

'''Work is a on going to get this build system functional!'''

Cmake is a cross-platform build system know to work on all major platforms we support (*nix, Windows, OSX).

CMake is an extensible, open-source system that has many powerful features.
Those features include:

* Supports complex, large build environments. CMake has been proven in several large projects (KDE, ParaView, SecondLife, Scribus)
* Generates native build files (e.g., makefiles on Unix; workspaces/projects on MS Visual C++). Therefore, standard tools can be used on any platform/compiler configuration.
* Powerful system introspection abilities including the ability to find installed include files, libraries and executables. Also the ability to test the compiler for supported features.
* Integrated testing system called CTest.
* Integrated packaging system called CPack.
* Easy integration with CDash and Dart dashboard servers.
* Powerful scripting language with simple syntax.
* Supports in-place and out-of-place builds. Multiple compilation trees are possible from a single source tree.
* Can be easily extended to add new features.
* CMake is open source, under a liberal BSD license.
* CMake operates with a cache designed to be interfaced with a graphical editor. The cache provides optional interaction to conditionally control the build process.
* Ability to create Mac OSX Frameworks and Application Bundles.
* Supports adding complex custom rules to the build.

== How you can help ==

We have completed the building of the CMakeLists.txt for almost everything needed.
We are now working on get the build to compile properly. See below Testing/Using to help.

There is a separate [[CMake Tasks]] page with things that are left to do w.r.t. cmake building of Inkscape.

== SIMPLE CmakeLists.txt ==
SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
)

== SIMPLE with single sub-directory Cmakelists.txt ==

SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
#Add our subdirectory sourcelist Var
${libavoid_parameter_SRC}
)
# this adds a single sub-directory
ADD_SUBDIRECTORY(parameter)

== Using CMake to build Inkscape ==

Experience with Scribus '''strongly''' suggests using an "out of source"build arrangement. E.g.

<pre>
mkdir buildinkscape
cd buildinkscape
cmake /path/to/inkscape
make
</pre>

/path/to/inkscape is the folder where you checked out inkscape to.

References:
[http://docs.scribus.net/index.php?lang=en&page=install4 Installing Scribus with Cmake] 
[http://docs.scribus.net/index.php?lang=en&page=install5 Installing with CMake on OSX]

== Using CMake to run tests ==

First, install Google Test framework by running download-gtest.sh in the main directory of inkscape source:

<pre>
cd /path/to/inkscape
bash download-gtest.sh
</pre>

Then, toggle the CMake config var "WITH_GTEST" to ON, e.g. by editing CMakeCache.txt, or by passing "-DWITH_GTEST=ON" to cmake. Don't forget to re-run cmake after the configuration change:

<pre>
cd /path/to/buildinkscape
# modify CMakeCache.txt
cmake ../inkscape
</pre>

Finally, run "make check" from same directory to run the tests:

<pre>
make check
</pre>

== Configuring your build further ==

It is possible to change some more options of the build, e.g. whether to compile against GTK2 or GTK3 libraries. If you fiddle a lot with this, you may want to install the interactive cmake configuration tool "ccmake", like so:
[[File:CCMAKE.PNG|200px|thumb|right|ccmake screen capture]]
<pre>
sudo apt-get install cmake-curses-gui
ccmake ../inkscape # In buildinkscape folder
</pre>

The ccmake utility will have features to re-run cmake for you before exiting. 
For example you can use CMAKE_INSTALL_PREFIX Path in which "make install" installs Inkscape and allow handle multiple Inkscape instalations. 
Press enter on the line to edit. Press again to save, when all your changes are done press c to configure, exit help and press g to generate. After this you exit ccmake and can finish with make.

=== adding options to cmake ===

you can specify some variable on cmake invokation. i.e.

<pre>
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug
</pre>

Useful CMake configuration variables include

* CMAKE_BUILD_TYPE: Either Release or Debug (a string).
* WITH_GTK3_EXPERIMENTAL: ON/OFF. Toggle between GTK2 or GTK3 ui toolkit.
* CMAKE_INSTALL_PREFIX: Path in which "make install" installs Inkscape.

CMake

2016-05-11T09:21:06Z

Objarni: /* Using CMake to build Inkscape */

'''Work is a on going to get this build system functional!'''

Cmake is a cross-platform build system know to work on all major platforms we support (*nix, Windows, OSX).

CMake is an extensible, open-source system that has many powerful features.
Those features include:

* Supports complex, large build environments. CMake has been proven in several large projects (KDE, ParaView, SecondLife, Scribus)
* Generates native build files (e.g., makefiles on Unix; workspaces/projects on MS Visual C++). Therefore, standard tools can be used on any platform/compiler configuration.
* Powerful system introspection abilities including the ability to find installed include files, libraries and executables. Also the ability to test the compiler for supported features.
* Integrated testing system called CTest.
* Integrated packaging system called CPack.
* Easy integration with CDash and Dart dashboard servers.
* Powerful scripting language with simple syntax.
* Supports in-place and out-of-place builds. Multiple compilation trees are possible from a single source tree.
* Can be easily extended to add new features.
* CMake is open source, under a liberal BSD license.
* CMake operates with a cache designed to be interfaced with a graphical editor. The cache provides optional interaction to conditionally control the build process.
* Ability to create Mac OSX Frameworks and Application Bundles.
* Supports adding complex custom rules to the build.

== How you can help ==

We have completed the building of the CMakeLists.txt for almost everything needed.
We are now working on get the build to compile properly. See below Testing/Using to help.

There is a separate [[CMake Tasks]] page with things that are left to do w.r.t. cmake building of Inkscape.

== SIMPLE CmakeLists.txt ==
SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
)

== SIMPLE with single sub-directory Cmakelists.txt ==

SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
#Add our subdirectory sourcelist Var
${libavoid_parameter_SRC}
)
# this adds a single sub-directory
ADD_SUBDIRECTORY(parameter)

== Using CMake to build Inkscape ==

Experience with Scribus '''strongly''' suggests using an "out of source"build arrangement. E.g.

<pre>
mkdir buildinkscape
cd buildinkscape
cmake path/to/inkscape/sources
make
</pre>

References:
[http://docs.scribus.net/index.php?lang=en&page=install4 Installing Scribus with Cmake] 
[http://docs.scribus.net/index.php?lang=en&page=install5 Installing with CMake on OSX]

== Using CMake to run tests ==

First, install Google Test framework by running download-gtest.sh in the main directory of inkscape source:

<pre>
cd /path/to/inkscape
bash download-gtest.sh
</pre>

Then, toggle the CMake config var "WITH_GTEST" to ON, e.g. by editing CMakeCache.txt, or by passing "-DWITH_GTEST=ON" to cmake. Don't forget to re-run cmake after the configuration change:

<pre>
cd /path/to/buildinkscape
# modify CMakeCache.txt
cmake ../inkscape
</pre>

Finally, run "make check" from same directory to run the tests:

<pre>
make check
</pre>

== Configuring your build further ==

It is possible to change some more options of the build, e.g. whether to compile against GTK2 or GTK3 libraries. If you fiddle a lot with this, you may want to install the interactive cmake configuration tool "ccmake", like so:
[[File:CCMAKE.PNG|200px|thumb|right|ccmake screen capture]]
<pre>
sudo apt-get install cmake-curses-gui
ccmake ../inkscape # In buildinkscape folder
</pre>

The ccmake utility will have features to re-run cmake for you before exiting. 
For example you can use CMAKE_INSTALL_PREFIX Path in which "make install" installs Inkscape and allow handle multiple Inkscape instalations. 
Press enter on the line to edit. Press again to save, when all your changes are done press c to configure, exit help and press g to generate. After this you exit ccmake and can finish with make.

=== adding options to cmake ===

you can specify some variable on cmake invokation. i.e.

<pre>
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug
</pre>

Useful CMake configuration variables include

* CMAKE_BUILD_TYPE: Either Release or Debug (a string).
* WITH_GTK3_EXPERIMENTAL: ON/OFF. Toggle between GTK2 or GTK3 ui toolkit.
* CMAKE_INSTALL_PREFIX: Path in which "make install" installs Inkscape.

GTK+ 3 issues

2016-05-05T20:48:28Z

Objarni: /* Issues */

This page is for Gtk documentation, any issues, questions or notes about the porting of inkscape to Gtk3. This document will be sent to the gtk/gnome developers and may be useful for Gimp developers who undergo the same process.

== Issues ==

Document your issues with porting Inkscape to Gtk3 below.

* [https://bugs.launchpad.net/inkscape/+bugs?field.tag=gtk3 GTK 3 Bugs]
* Jumping palette. The color bar/palette does not seem to be able to decide how high it should be, at least for some combinations of palette width, height, etc. See launchpad bug [https://bugs.launchpad.net/inkscape/+bug/1201545 #1201545].
** This might have been fixed by r14870 - the icon clipping problem.
* <strike>Icons are too small / cut. (if someone can find the launchpad bug for this one, please add link here). This is probably caused by the use of SPIcon instead of a standard GtkImage widget.</strike>
** The clipping of icons in the toolbar is fixed in r14870. Problem had to do with custom button widget which wraps icon. The preferred/minimum width/height was not taking into account the padding around the icon.
** We have too many ways of creating buttons with icons which leads to inconsistency of behavior.
* All custom widgets now use the Cairo drawing model. All need to be fully tested, and several (e.g., the filter editor) are not rendered correctly.
* Several of the Gtk+ widgets have changed their layout (in particular, the GtkSpinButton is now much wider). Many of the toolbars now overflow the screen horizontally, and many dialogs are now far too wide. The layout of affected containers should be redesigned to account for this.
* The rules for sizing of widgets within containers has changed in Gtk+ 3. In many cases, widgets will initially appear far too big, or with zero size. All dialogs and containers need to be checked for these issues.
* Mac Issues:
** No tablet input support on Mac (e.g. Wacom). MyPaint seems to be working on this.
*** https://community.mypaint.org/t/how-to-build-mypaint-on-mac-osx-without-macports/344
*** https://bugzilla.gnome.org/show_bug.cgi?id=695701
** Support for global menu bar.
*** GEdit uses OSX menu bar and has native file dialogs
* The text "Blur" and "Opacity" inside the "interactive progress bar" widgets (are these custom widgets?) in Fill and stroke dialog are cut in half or less, and are rendered unreadable. There is also some different modes of interaction, with top half of the widgets meaning "move instantly to this point" and (part of) bottom half meaning "slightly adjust value", however the latter is really hard to use as it's something like on or two pixel rows high.

== Standard Practice ==

List any repetative actions during the upgrade and note anything that needed doing when moving from gtk2 to gtk3 widgets (for examine hbox and vbox) be clear if the action is using gtk3 or gtkmm (which often papers over some of the move to gtk3)

* GtkHBox and GtkVBox are now just GtkBox with an orientation attribute.

== Widgets ==

List any and all custom widgets currently being used in Inkscape.

* Rulers - src/widgets/ruler.cpp
** Should probably be updated from GIMP.
* SPIcon - src/widgets/icon.cpp
** Should be replaced with regular GtkImage.
** SPIcon does more than rendering the icon:
**# Handles custom size: Inkscape::ICON_SIZE_DECORATION
**# Old to new icon name conversion
**# Rendering icons from icon.svg
**# Rendering into cache
** All the above could be removed.
* SPCanvas - src/display/sp-canvas.cpp
** Needs to stay a custom widget. Fixed for GTK3.

== Ideas ==

Any ideas which are interesting

* No ideas yet

== Deferred changes ==

Work items, which should be carried out after the release of Inkscape 0.93. These are tasks, which would be impractical to perform until after we have permanently ended our support for Gtk+ 2. For example, these may make use of new Gtk+ 3 features, which have no simple fallback available in Gtk+ 2.

* Delete all Gtk+ 2 backward-compatibility code. This will remove over 700 blocks of conditional build instructions from our code base, and thousands of lines of redundant code. This is essential for future maintainability, and will greatly simplify future work on Gtk+ 3 features.
* Load all theme information from an external CSS style sheet. This will potentially tidy our code by removing hard-coded styling instructions, and will make it possible to properly apply user themes to Inkscape.
* Switch to using a GtkIconTheme, with all custom icons installed in a standard way instead of bundled within a single SVG document. This will make it easier to provide user icon themes, and get rid of a lot of deprecated code.
** We should also unify all the code for creating buttons with icons.
** GTK3 respects the HiDPI setting while GTK2 does not. System icons are rendered with high DPI when needed but Inkscape specific icons are not. This will probably be fixed by moving to GtkIconTheme.
** Many GTK methods using GtkIconSize have been deprecated but GtkIconSize itself has not been. This can be confusing. We have a custom value for GtkIconSize that we should try to remove.
* Switch to using GtkApplication instead of GtkMain.
* Switch to using GAction instead of GtkAction <- this one might be deferred indefinitely; see Gimp's direction for comparison (Gimp has stated they will not switch).

GTK+ 3 issues

2016-05-05T20:45:42Z

Objarni: /* Issues */ added issue about blur and opacity widgets

This page is for Gtk documentation, any issues, questions or notes about the porting of inkscape to Gtk3. This document will be sent to the gtk/gnome developers and may be useful for Gimp developers who undergo the same process.

== Issues ==

Document your issues with porting Inkscape to Gtk3 below.

* [https://bugs.launchpad.net/inkscape/+bugs?field.tag=gtk3 GTK 3 Bugs]
* Jumping palette. The color bar/palette does not seem to be able to decide how high it should be, at least for some combinations of palette width, height, etc. See launchpad bug [https://bugs.launchpad.net/inkscape/+bug/1201545 #1201545].
* <strike>Icons are too small / cut. (if someone can find the launchpad bug for this one, please add link here). This is probably caused by the use of SPIcon instead of a standard GtkImage widget.</strike>
** The clipping of icons in the toolbar is fixed in r14870. Problem had to do with custom button widget which wraps icon. The preferred/minimum width/height was not taking into account the padding around the icon.
** We have too many ways of creating buttons with icons which leads to inconsistency of behavior.
* All custom widgets now use the Cairo drawing model. All need to be fully tested, and several (e.g., the filter editor) are not rendered correctly.
* Several of the Gtk+ widgets have changed their layout (in particular, the GtkSpinButton is now much wider). Many of the toolbars now overflow the screen horizontally, and many dialogs are now far too wide. The layout of affected containers should be redesigned to account for this.
* The rules for sizing of widgets within containers has changed in Gtk+ 3. In many cases, widgets will initially appear far too big, or with zero size. All dialogs and containers need to be checked for these issues.
* Mac Issues:
** No tablet input support on Mac (e.g. Wacom). MyPaint seems to be working on this.
*** https://community.mypaint.org/t/how-to-build-mypaint-on-mac-osx-without-macports/344
*** https://bugzilla.gnome.org/show_bug.cgi?id=695701
** Support for global menu bar.
*** GEdit uses OSX menu bar and has native file dialogs
* The text "Blur" and "Opacity" inside the "interactive progress bar" widgets (are these custom widgets?) in Fill and stroke dialog are cut in half or less, and are rendered unreadable. There is also some different modes of interaction, with top half of the widgets meaning "move instantly to this point" and (part of) bottom half meaning "slightly adjust value", however the latter is really hard to use as it's something like on or two pixel rows high.

== Standard Practice ==

List any repetative actions during the upgrade and note anything that needed doing when moving from gtk2 to gtk3 widgets (for examine hbox and vbox) be clear if the action is using gtk3 or gtkmm (which often papers over some of the move to gtk3)

* GtkHBox and GtkVBox are now just GtkBox with an orientation attribute.

== Widgets ==

List any and all custom widgets currently being used in Inkscape.

* Rulers - src/widgets/ruler.cpp
** Should probably be updated from GIMP.
* SPIcon - src/widgets/icon.cpp
** Should be replaced with regular GtkImage.
** SPIcon does more than rendering the icon:
**# Handles custom size: Inkscape::ICON_SIZE_DECORATION
**# Old to new icon name conversion
**# Rendering icons from icon.svg
**# Rendering into cache
** All the above could be removed.
* SPCanvas - src/display/sp-canvas.cpp
** Needs to stay a custom widget. Fixed for GTK3.

== Ideas ==

Any ideas which are interesting

* No ideas yet

== Deferred changes ==

Work items, which should be carried out after the release of Inkscape 0.93. These are tasks, which would be impractical to perform until after we have permanently ended our support for Gtk+ 2. For example, these may make use of new Gtk+ 3 features, which have no simple fallback available in Gtk+ 2.

* Delete all Gtk+ 2 backward-compatibility code. This will remove over 700 blocks of conditional build instructions from our code base, and thousands of lines of redundant code. This is essential for future maintainability, and will greatly simplify future work on Gtk+ 3 features.
* Load all theme information from an external CSS style sheet. This will potentially tidy our code by removing hard-coded styling instructions, and will make it possible to properly apply user themes to Inkscape.
* Switch to using a GtkIconTheme, with all custom icons installed in a standard way instead of bundled within a single SVG document. This will make it easier to provide user icon themes, and get rid of a lot of deprecated code.
** We should also unify all the code for creating buttons with icons.
** GTK3 respects the HiDPI setting while GTK2 does not. System icons are rendered with high DPI when needed but Inkscape specific icons are not. This will probably be fixed by moving to GtkIconTheme.
** Many GTK methods using GtkIconSize have been deprecated but GtkIconSize itself has not been. This can be confusing. We have a custom value for GtkIconSize that we should try to remove.
* Switch to using GtkApplication instead of GtkMain.
* Switch to using GAction instead of GtkAction <- this one might be deferred indefinitely; see Gimp's direction for comparison (Gimp has stated they will not switch).

GTK+ 3 issues

2016-05-04T10:39:10Z

Objarni: /* Widgets */

This page is for Gtk documentation, any issues, questions or notes about the porting of inkscape to Gtk3. This document will be sent to the gtk/gnome developers and may be useful for Gimp developers who undergo the same process.

== Issues ==

Document your issues with porting Inkscape to Gtk3 below.

* [https://bugs.launchpad.net/inkscape/+bugs?field.tag=gtk3 GTK 3 Bugs]
* Jumping palette. The color bar/palette does not seem to be able to decide how high it should be, at least for some combinations of palette width, height, etc. See launchpad bug [https://bugs.launchpad.net/inkscape/+bug/1201545 #1201545].
* <strike>Icons are too small / cut. (if someone can find the launchpad bug for this one, please add link here). This is probably caused by the use of SPIcon instead of a standard GtkImage widget.</strike>
** The clipping of icons in the toolbar is fixed in r14870. Problem had to do with custom button widget which wraps icon. The preferred/minimum width/height was not taking into account the padding around the icon.
** We have too many ways of creating buttons with icons which leads to inconsistency of behavior.
* All custom widgets now use the Cairo drawing model. All need to be fully tested, and several (e.g., the filter editor) are not rendered correctly.
* Several of the Gtk+ widgets have changed their layout (in particular, the GtkSpinButton is now much wider). Many of the toolbars now overflow the screen horizontally, and many dialogs are now far too wide. The layout of affected containers should be redesigned to account for this.
* The rules for sizing of widgets within containers has changed in Gtk+ 3. In many cases, widgets will initially appear far too big, or with zero size. All dialogs and containers need to be checked for these issues.

== Standard Practice ==

List any repetative actions during the upgrade and note anything that needed doing when moving from gtk2 to gtk3 widgets (for examine hbox and vbox) be clear if the action is using gtk3 or gtkmm (which often papers over some of the move to gtk3)

* GtkHBox and GtkVBox are now just GtkBox with an orientation attribute.

== Widgets ==

List any and all custom widgets currently being used in Inkscape.

* Rulers - src/widgets/ruler.cpp
** Should probably be updated from GIMP.
* SPIcon - src/widgets/icon.cpp
** Should be replaced with regular GtkImage.
** SPIcon does much more than just rendering the icon. I (Tav) don't think it can be replaced by GtkImage.
*** What more does it do? (objarni)
* SPCanvas - src/display/sp-canvas.cpp
** Needs to stay a custom widget. Fixed for GTK3.

== Ideas ==

Any ideas which are interesting

* No ideas yet

== Deferred changes ==

Work items, which should be carried out after the release of Inkscape 0.93. These are tasks, which would be impractical to perform until after we have permanently ended our support for Gtk+ 2. For example, these may make use of new Gtk+ 3 features, which have no simple fallback available in Gtk+ 2.

* Delete all Gtk+ 2 backward-compatibility code. This will remove over 700 blocks of conditional build instructions from our code base, and thousands of lines of redundant code. This is essential for future maintainability, and will greatly simplify future work on Gtk+ 3 features.
* Load all theme information from an external CSS style sheet. This will potentially tidy our code by removing hard-coded styling instructions, and will make it possible to properly apply user themes to Inkscape.
* Switch to using a GtkIconTheme, with all custom icons installed in a standard way instead of bundled within a single SVG document. This will make it easier to provide user icon themes, and get rid of a lot of deprecated code.
** We should also unify all the code for creating buttons with icons.
** GTK3 respects the HiDPI setting while GTK2 does not. System icons are rendered with high DPI when needed but Inkscape specific icons are not. This will probably be fixed by moving to GtkIconTheme.
** Many GTK methods using GtkIconSize have been deprecated but GtkIconSize itself has not been. This can be confusing. We have a custom value for GtkIconSize that we should try to remove.
* Switch to using GtkApplication instead of GtkMain.
* Switch to using GAction instead of GtkAction <- this one might be deferred indefinitely; see Gimp's direction for comparison (Gimp has stated they will not switch).

GTK+ 3 issues

2016-05-04T10:34:32Z

Objarni: /* Issues */

This page is for Gtk documentation, any issues, questions or notes about the porting of inkscape to Gtk3. This document will be sent to the gtk/gnome developers and may be useful for Gimp developers who undergo the same process.

== Issues ==

Document your issues with porting Inkscape to Gtk3 below.

* [https://bugs.launchpad.net/inkscape/+bugs?field.tag=gtk3 GTK 3 Bugs]
* Jumping palette. The color bar/palette does not seem to be able to decide how high it should be, at least for some combinations of palette width, height, etc. See launchpad bug [https://bugs.launchpad.net/inkscape/+bug/1201545 #1201545].
* <strike>Icons are too small / cut. (if someone can find the launchpad bug for this one, please add link here). This is probably caused by the use of SPIcon instead of a standard GtkImage widget.</strike>
** The clipping of icons in the toolbar is fixed in r14870. Problem had to do with custom button widget which wraps icon. The preferred/minimum width/height was not taking into account the padding around the icon.
** We have too many ways of creating buttons with icons which leads to inconsistency of behavior.
* All custom widgets now use the Cairo drawing model. All need to be fully tested, and several (e.g., the filter editor) are not rendered correctly.
* Several of the Gtk+ widgets have changed their layout (in particular, the GtkSpinButton is now much wider). Many of the toolbars now overflow the screen horizontally, and many dialogs are now far too wide. The layout of affected containers should be redesigned to account for this.
* The rules for sizing of widgets within containers has changed in Gtk+ 3. In many cases, widgets will initially appear far too big, or with zero size. All dialogs and containers need to be checked for these issues.

== Standard Practice ==

List any repetative actions during the upgrade and note anything that needed doing when moving from gtk2 to gtk3 widgets (for examine hbox and vbox) be clear if the action is using gtk3 or gtkmm (which often papers over some of the move to gtk3)

* GtkHBox and GtkVBox are now just GtkBox with an orientation attribute.

== Widgets ==

List any and all custom widgets currently being used in Inkscape.

* Rulers - src/widgets/ruler.cpp
** Should probably be updated from GIMP.
* SPIcon - src/widgets/icon.cpp
** Should be replaced with regular GtkImage.
** SPIcon does much more than just rendering the icon. I (Tav) don't think it can be replaced by GtkImage.
* SPCanvas - src/display/sp-canvas.cpp
** Needs to stay a custom widget. Fixed for GTK3.

== Ideas ==

Any ideas which are interesting

* No ideas yet

== Deferred changes ==

Work items, which should be carried out after the release of Inkscape 0.93. These are tasks, which would be impractical to perform until after we have permanently ended our support for Gtk+ 2. For example, these may make use of new Gtk+ 3 features, which have no simple fallback available in Gtk+ 2.

* Delete all Gtk+ 2 backward-compatibility code. This will remove over 700 blocks of conditional build instructions from our code base, and thousands of lines of redundant code. This is essential for future maintainability, and will greatly simplify future work on Gtk+ 3 features.
* Load all theme information from an external CSS style sheet. This will potentially tidy our code by removing hard-coded styling instructions, and will make it possible to properly apply user themes to Inkscape.
* Switch to using a GtkIconTheme, with all custom icons installed in a standard way instead of bundled within a single SVG document. This will make it easier to provide user icon themes, and get rid of a lot of deprecated code.
** We should also unify all the code for creating buttons with icons.
** GTK3 respects the HiDPI setting while GTK2 does not. System icons are rendered with high DPI when needed but Inkscape specific icons are not. This will probably be fixed by moving to GtkIconTheme.
** Many GTK methods using GtkIconSize have been deprecated but GtkIconSize itself has not been. This can be confusing. We have a custom value for GtkIconSize that we should try to remove.
* Switch to using GtkApplication instead of GtkMain.
* Switch to using GAction instead of GtkAction <- this one might be deferred indefinitely; see Gimp's direction for comparison (Gimp has stated they will not switch).

GTK+ 3 issues

2016-05-02T07:18:11Z

Objarni: /* Issues */ better formatting

GTK+ 3 issues

2016-05-02T07:17:37Z

Objarni: /* Issues */ added a couple of issues

CMake

2016-04-16T08:27:22Z

Objarni: /* Configuring your build further */

'''Work is a on going to get this build system functional!'''

Cmake is a cross-platform build system know to work on all major platforms we support (*nix, Windows, OSX).

CMake is an extensible, open-source system that has many powerful features.
Those features include:

* Supports complex, large build environments. CMake has been proven in several large projects (KDE, ParaView, SecondLife, Scribus)
* Generates native build files (e.g., makefiles on Unix; workspaces/projects on MS Visual C++). Therefore, standard tools can be used on any platform/compiler configuration.
* Powerful system introspection abilities including the ability to find installed include files, libraries and executables. Also the ability to test the compiler for supported features.
* Integrated testing system called CTest.
* Integrated packaging system called CPack.
* Easy integration with CDash and Dart dashboard servers.
* Powerful scripting language with simple syntax.
* Supports in-place and out-of-place builds. Multiple compilation trees are possible from a single source tree.
* Can be easily extended to add new features.
* CMake is open source, under a liberal BSD license.
* CMake operates with a cache designed to be interfaced with a graphical editor. The cache provides optional interaction to conditionally control the build process.
* Ability to create Mac OSX Frameworks and Application Bundles.
* Supports adding complex custom rules to the build.

== How you can help ==

We have completed the building of the CMakeLists.txt for almost everything needed.
We are now working on get the build to compile properly. See below Testing/Using to help.

There is a separate [[CMake Tasks]] page with things that are left to do w.r.t. cmake building of Inkscape.

== SIMPLE CmakeLists.txt ==
SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
)

== SIMPLE with single sub-directory Cmakelists.txt ==

SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
#Add our subdirectory sourcelist Var
${libavoid_parameter_SRC}
)
# this adds a single sub-directory
ADD_SUBDIRECTORY(parameter)

== Using CMake to build Inkscape ==

Experience with Scribus '''strongly''' suggests using an "out of source"build arrangement. E.g.

<pre>
mkdir buildinkscape
cd buildinkscape
cmake ./path/to/inkscape/sources
make
</pre>

References:
[http://docs.scribus.net/index.php?lang=en&page=install4 Installing Scribus with Cmake] 
[http://docs.scribus.net/index.php?lang=en&page=install5 Installing with CMake on OSX]

== Using CMake to run tests ==

First, install Google Test framework by running download-gtest.sh in the main directory of inkscape source:

<pre>
cd /path/to/inkscape
bash download-gtest.sh
</pre>

Then, toggle the CMake config var "WITH_GTEST" to ON, e.g. by editing CMakeCache.txt, or by passing "-DWITH_GTEST=ON" to cmake. Don't forget to re-run cmake after the configuration change:

<pre>
cd /path/to/buildinkscape
# modify CMakeCache.txt
cmake ../inkscape
</pre>

Finally, run "make check" from same directory to run the tests:

<pre>
make check
</pre>

== Configuring your build further ==

It is possible to change some more options of the build, e.g. whether to compile against GTK2 or GTK3 libraries. If you fiddle a lot with this, you may want to install the interactive cmake configuration tool "ccmake", like so:

<pre>
sudo apt-get install cmake-curses-gui
ccmake ../inkscape # In buildinkscape folder
</pre>

The ccmake utility will have features to re-run cmake for you before exiting.

Useful CMake configuration variables include

* CMAKE_BUILD_TYPE: Either Release or Debug (a string).
* WITH_GTK3_EXPERIMENTAL: ON/OFF. Toggle between GTK2 or GTK3 ui toolkit.
* CMAKE_INSTALL_PREFIX: Path in which "make install" installs Inkscape.

CMake

2016-04-15T18:52:23Z

Objarni:

'''Work is a on going to get this build system functional!'''

Cmake is a cross-platform build system know to work on all major platforms we support (*nix, Windows, OSX).

CMake is an extensible, open-source system that has many powerful features.
Those features include:

* Supports complex, large build environments. CMake has been proven in several large projects (KDE, ParaView, SecondLife, Scribus)
* Generates native build files (e.g., makefiles on Unix; workspaces/projects on MS Visual C++). Therefore, standard tools can be used on any platform/compiler configuration.
* Powerful system introspection abilities including the ability to find installed include files, libraries and executables. Also the ability to test the compiler for supported features.
* Integrated testing system called CTest.
* Integrated packaging system called CPack.
* Easy integration with CDash and Dart dashboard servers.
* Powerful scripting language with simple syntax.
* Supports in-place and out-of-place builds. Multiple compilation trees are possible from a single source tree.
* Can be easily extended to add new features.
* CMake is open source, under a liberal BSD license.
* CMake operates with a cache designed to be interfaced with a graphical editor. The cache provides optional interaction to conditionally control the build process.
* Ability to create Mac OSX Frameworks and Application Bundles.
* Supports adding complex custom rules to the build.

== How you can help ==

We have completed the building of the CMakeLists.txt for almost everything needed.
We are now working on get the build to compile properly. See below Testing/Using to help.

There is a separate [[CMake Tasks]] page with things that are left to do w.r.t. cmake building of Inkscape.

== SIMPLE CmakeLists.txt ==
SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
)

== SIMPLE with single sub-directory Cmakelists.txt ==

SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
#Add our subdirectory sourcelist Var
${libavoid_parameter_SRC}
)
# this adds a single sub-directory
ADD_SUBDIRECTORY(parameter)

== Using CMake to build Inkscape ==

Experience with Scribus '''strongly''' suggests using an "out of source"build arrangement. E.g.

<pre>
mkdir buildinkscape
cd buildinkscape
cmake ./path/to/inkscape/sources
make
</pre>

References:
[http://docs.scribus.net/index.php?lang=en&page=install4 Installing Scribus with Cmake] 
[http://docs.scribus.net/index.php?lang=en&page=install5 Installing with CMake on OSX]

== Using CMake to run tests ==

First, install Google Test framework by running download-gtest.sh in the main directory of inkscape source:

<pre>
cd /path/to/inkscape
bash download-gtest.sh
</pre>

Then, toggle the CMake config var "WITH_GTEST" to ON, e.g. by editing CMakeCache.txt, or by passing "-DWITH_GTEST=ON" to cmake. Don't forget to re-run cmake after the configuration change:

<pre>
cd /path/to/buildinkscape
# modify CMakeCache.txt
cmake ../inkscape
</pre>

Finally, run "make check" from same directory to run the tests:

<pre>
make check
</pre>

== Configuring your build further ==

It is possible to change some more options of the build, e.g. whether to compile against GTK2 or GTK3 libraries. If you fiddle a lot with this, you may want to install the interactive cmake configuration tool "ccmake", like so:

<pre>
sudo apt-get install cmake-curses-gui
ccmake ../inkscape # In buildinkscape folder
</pre>

The ccmake utility will have features to re-run cmake for you before exiting.

CMake

2016-04-15T13:57:21Z

Objarni: /* Testing/Using */

'''Work is a on going to get this build system functional!'''

Cmake is a cross-platform build system know to work on all major platforms we support (*nix, Windows, OSX).

CMake is an extensible, open-source system that has many powerful features.
Those features include:

* Supports complex, large build environments. CMake has been proven in several large projects (KDE, ParaView, SecondLife, Scribus)
* Generates native build files (e.g., makefiles on Unix; workspaces/projects on MS Visual C++). Therefore, standard tools can be used on any platform/compiler configuration.
* Powerful system introspection abilities including the ability to find installed include files, libraries and executables. Also the ability to test the compiler for supported features.
* Integrated testing system called CTest.
* Integrated packaging system called CPack.
* Easy integration with CDash and Dart dashboard servers.
* Powerful scripting language with simple syntax.
* Supports in-place and out-of-place builds. Multiple compilation trees are possible from a single source tree.
* Can be easily extended to add new features.
* CMake is open source, under a liberal BSD license.
* CMake operates with a cache designed to be interfaced with a graphical editor. The cache provides optional interaction to conditionally control the build process.
* Ability to create Mac OSX Frameworks and Application Bundles.
* Supports adding complex custom rules to the build.

== How you can help ==

We have completed the building of the CMakeLists.txt for almost everything needed.
We are now working on get the build to compile properly. See below Testing/Using to help.

There is a separate [[CMake Tasks]] page with things that are left to do w.r.t. cmake building of Inkscape.

== SIMPLE CmakeLists.txt ==
SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
)

== SIMPLE with single sub-directory Cmakelists.txt ==

SET(libavoid_SRC
connector.cpp
geometry.cpp
graph.cpp
makepath.cpp
polyutil.cpp
region.cpp
router.cpp
shape.cpp
static.cpp
timer.cpp
vertices.cpp
visibility.cpp
#Add our subdirectory sourcelist Var
${libavoid_parameter_SRC}
)
# this adds a single sub-directory
ADD_SUBDIRECTORY(parameter)

== Using CMake to build Inkscape ==

Experience with Scribus '''strongly''' suggests using an "out of source"build arrangement. E.g.

<pre>
mkdir buildinkscape
cd buildinkscape
cmake ./path/to/inkscape/sources
make
</pre>

References:
[http://docs.scribus.net/index.php?lang=en&page=install4 Installing Scribus with Cmake] 
[http://docs.scribus.net/index.php?lang=en&page=install5 Installing with CMake on OSX]

== Using CMake to run tests ==

First, install Google Test framework by running download-gtest.sh in root of inkscape source:

<pre>
cd /path/to/inkscape
./download-gtest.sh
</pre>

Then, toggle the CMake config var "WITH_GTEST" to ON, e.g. by editing CMakeCache.txt or by using ccmake. Don't forget to re-run cmake after the configuration change:

<pre>
cd /path/to/buildinkscape
# modify CMakeCache.txt
cmake ../inkscape
</pre>

Finally, run "make check" from same directory to run the tests:

<pre>
make check
</pre>

CMake

2016-04-15T11:31:37Z

Objarni: /* How you can help */

Working with CMake

2016-04-15T09:15:54Z

Objarni: /* Print full command line used when building */

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Print full command line used when building ==

When you produce Makefiles using cmake, and make fails, you can get verbose output e.g. the full gcc command line used for compilation, by adding VERBOSE=1 to make:

$ make VERBOSE=1

== Clean up cmake cache ==
If you end up in a dead-end with things not building anymore, you can clean the cmake cached files by issuing

$ make clean-cmake-files

.. followed by regenerating the Makefiles:

$ cmake ../inkscape

Note that this will require a full-rebuild of the whole of Inkscape

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-15T08:16:16Z

Objarni: /* Clean up cmake cache */

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Print full command line used when building ==

When you produce Makefiles using cmake, you can you the following to print the full compiler command lines used to build project:

$ make VERBOSE=1

== Clean up cmake cache ==
If you end up in a dead-end with things not building anymore, you can clean the cmake cached files by issuing

$ make clean-cmake-files

.. followed by regenerating the Makefiles:

$ cmake ../inkscape

Note that this will require a full-rebuild of the whole of Inkscape

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-15T08:15:17Z

Objarni: /* Your First CMake Script */

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Print full command line used when building ==

When you produce Makefiles using cmake, you can you the following to print the full compiler command lines used to build project:

$ make VERBOSE=1

== Clean up cmake cache ==
If you end up in a dead-end with things not building anymore, you can clean the cmake cached files by issuing

$ make clean-cmake-files

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-14T18:03:01Z

Objarni: /* Your First CMake Script */

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

Print full command line used when building
==========================================

When you produce Makefiles using cmake, you can you the following to print the full compiler command lines used to build project:

$ make VERBOSE=1

== Clean up cmake cache ==
If you end up in a dead-end with things not building anymore, you can clean the cmake cached files by issuing

$ make clean-cmake-files

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-13T13:11:05Z

Objarni:

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Clean up cmake cache ==
If you end up in a dead-end with things not building anymore, you can clean the cmake cached files by issuing

$ make clean-cmake-files

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-13T12:41:08Z

Objarni:

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file and exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake without not mess up the source folder with build artefacts:

$ cd ..
$ mkdir cmake-tutorial-build

Now run cmake in the build directory, specifying the path to the source directory:

$ cd cmake-tutorial-build
$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions

Working with CMake

2016-04-13T11:39:50Z

Objarni: cmake encourages separation of source and build directories, the example now adheres to that convention

This is a developer-oriented introduction to CMake and how to modify the CMake build scripts.

We assume you already know the basics of how to use cmake to configure and build Inkscape (if not, see Inkscape's README).

== Functions and Variables ==

cmake has its own language and syntax, but it's pretty simple. Essentially, everything is a function call.

message("Hello world!")

Even just setting variables is a function call:

set(MYVAR "foobar")

Function calls have parenthesis but arguments aren't separated with commas, just whitespace. It's fine to add newlines between arguments inside the parens. CMake isn't strict about casing for function names, so SET() and set() are equivalent, but it is strict about variable name casing. We'll adopt the convention of keeping function names lower case, and variable names upper case.

Strings don't always have to be quoted, although it's also a good convention to follow. So, these are all functionally equivalent in this case:

SET(MYVAR "foobar")
set(MYVAR
foobar)
SET(MYVAR foobar)

Variables are referenced using a dollar sign and curly brackets:

set(MYVAR "foobar")
message("${MYVAR}")

== Your First CMake Script ==

You now know enough to create a trivial cmake program.

Create an empty directory and open a file named 'CMakeLists.txt' in your favorite text editor.

$ mkdir cmake-tutorial
$ cd cmake-tutorial
$ gedit CMakeLists.txt

Type the following lines into this CMakeLists.txt file:

set(MYVAR "foobar")
message("${MYVAR}")

Save the text file, exit your editor. The folder cmake-tutorial is your source folder from cmakes perspective
and you need a build directory to run cmake and not mess up this folder with build artefacts:

cd ..
mkdir cmake-tutorial-build
cd cmake-tutorial-build

Now run cmake in the build directory, specifying the source directory:

$ cmake ../cmake-tutorial
foobar
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/cmake-tutorial

CMake will automatically recognize "CMakeLists.txt" as its config file. CMake assumes that the current directory is where we want all our stuff built to. The '.' argument to the cmake command tells CMake to look in the current directory for source files.

== Pre-defined Variables ==

As you can imagine, CMake provides a broad set of pre-defined variables that relate to build systems.

It has a bunch to help determine what platform the build is building for:

message("UNIX: ${UNIX}")
message("APPLE: ${APPLE}")
message("WIN32: ${WIN32}")
message("MSVC: ${MSVC}")

Prints for me:

UNIX: 1
APPLE:
WIN32:
MSVC:

CMake also has a slew of variables to keep track of directories that things should go to:

PROJECT_SOURCE_DIR
CMAKE_SOURCE_DIR
CMAKE_CURRENT_SOURCE_DIR
PROJECT_BINARY_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_BINARY_DIR
CMAKE_INSTALL_PREFIX

Let's take a closer look at these:

message("PROJECT_NAME ${PROJECT_NAME}")
message("PROJECT_SOURCE_DIR ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR ${CMAKE_SOURCE_DIR}")
message("CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}")
message("PROJECT_BINARY_DIR ${PROJECT_BINARY_DIR}")
message("CMAKE_BINARY_DIR ${CMAKE_BINARY_DIR}")
message("CMAKE_CURRENT_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX}")

For me this prints out:

PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_BINARY_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial
CMAKE_INSTALL_PREFIX /usr/local

The 'source' vs. 'binary' variables are the same if the user is doing an in-tree build but differ if out-of-tree. Generally, if you do out-of-tree builds yourself, you can be reasonably confident your code will work either way.

The 'current' variables come into play when you have a directory hierarchy with CMakeList.txt files at various levels. Variables like CMAKE_CURRENT_SOURCE_DIR refer to the currently processing child location in the tree, whereas CMAKE_SOURCE_DIR will always reference the root of the source tree.

Also, be aware that the user is able to set their own installation prefix, so be careful about assumptions about where things will be installed.

Let's try building our example in a more complex way to see how these variables change:

$ mkdir build install
$ cd build && cmake .. -DCMAKE_INSTALL_PREFIX=../install
...
PROJECT_NAME Project
PROJECT_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_SOURCE_DIR /tmp/cmake-tutorial
CMAKE_CURRENT_SOURCE_DIR /tmp/cmake-tutorial
PROJECT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_CURRENT_BINARY_DIR /tmp/cmake-tutorial/build
CMAKE_INSTALL_PREFIX /tmp/cmake-tutorial/install
...

== Conditionals ==

'If' statements are pretty fundamental in all languages, but particularly so for configuring software. Here's how to do an if statement in CMake:

set(MYVAR "foobar")

if(MYVAR STREQUAL "foobar")
set(FOOBAR "yes")
endif()

if(FOOBAR)
message("Hello world!")
elseif(NOT DEFINED FOOBAR)
message("Your FOOBAR is fubar.")
else()
message("Goodbye, cruel world...")
endif()

Couple things to note - there's none of the usual ==, <, etc. boolean operators. Instead use EQUAL and LESS for numerical comparisons, STREQUAL, and STRLESS for strings. Other frequently used tests include EXISTS, DEFINED, AND, OR, and NOT. MATCHES provides a handy way to do regular expression testing on strings. VERSION_EQUAL, VERSION_LESS, and VERSION_GREATER are helpful for testing release version strings. There's a bunch of tests relating to checking status on files. Also notice in the second if statement, that FOOBAR's value of "yes" is automatically recognized as a true value. "no" is a false value.

For a complete list of available unary and binary tests and what CMake recognizes as true and false values, see https://cmake.org/cmake/help/v3.0/command/if.html.

== Strings ==

Basic text manipulation in CMake can be done via the string() routine. The first argument to the string() function is the operation to be performed - CONCAT, SUBSTRING, LENGTH, REGEX, COMPARE, MD5, etc.

cmake_minimum_required(VERSION 2.8)
set(A "foobar")
string(SUBSTRING "${A}" 3 3 B)
string(TOUPPER "${B}" C)
message("${C}")

Prints

BAR

Did you notice in this last example how we had a cmake_minimum_required() call?

CMake has grown in functionality since it was originally first introduced, and the cmake_minimum_required() let's us specify what level of compatibility our script expects. After all, the version of cmake installed on different users' systems is going to vary considerably so this is a very basic thing to check.

I don't know if there is a website somewhere that indicates what cmake functionality is available in which cmake versions. However, cmake seems to be good about warning us when we use something that requires a specific version of cmake, and warns us in this example if we don't specify what we require. Obviously we don't want to set the version *too* recent or else users will be unable to run cmake to build Inkscape!

== Lists ==

CMake strives to make handling lists of strings straightforward and easy. Basically, it handles lists as semi-colon delimited strings, and automatically handles converting back and forth:

set(FOOLIST a b c d e)
message("${FOOLIST}")
message(${FOOLIST})

Prints out

a;b;c;d;e
abcde

The [https://cmake.org/cmake/help/v3.0/command/string.html list() function] provides operations such as APPEND, REVERSE, SORT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, GET, etc. similar to string.

Iterating through the items can be done with a for loop:

cmake_minimum_required(VERSION 2.8)
set(FOOLIST a b c d e)
list(REMOVE_AT FOOLIST 1)
list(REMOVE_AT FOOLIST 2)
foreach(v ${FOOLIST})
message(${v})
list(APPEND LETTERS ${v})
endforeach()
message(${LETTERS})

Prints out

a
c
e
ace

== Files ==

Configuring a software project often involves fiddling with files. Configuration files may need settings changed in them. Generated code files need generated. Other files may need stuff substituted in them or read out of them. CMake has a wealth of functionality to help here.

The most basic would be reading the contents of a file into a variable consisting of a list of strings:

file(STRINGS /usr/share/inkscape/palettes/inkscape.gpl INKSCAPE_PALETTE)
list(GET INKSCAPE_PALETTE 0 1 PALETTE_NAME)
message("${PALETTE_NAME}")

Prints out:

GIMP Palette;Name: Inkscape default

Like list() and string(), the first argument to file() is the operation to perform. Other operations are WRITE, GLOB, REMOVE, TO_CMAKE_PATH, TIMESTAMP, COPY, and a bunch more. This routine is pretty powerful, as you can see from [https://cmake.org/cmake/help/v3.0/command/file.html the file() documentation].

== Building and Installing ==

Now that we've done a quick look at CMake's basic syntax, you should be comfortable with tinkering with Inkscape's CMakeLists.txt and other CMake config files. Now on to the nitty gritty of how to actually build code files into executables and get them installed on the system.

There are plenty of detailed tutorials out there for how to do this from scratch, which I'll suggest perusing if you're creating a cmake project from scratch. But if you're working on Inkscape's build system you really just need to know the key bits and pieces to look for.

First, you'll need a list of source code files. CMake's '''file()''' function has a GLOB operation that enables it to automatically find source files, but this is generally considered bad practice, so we'll typically list the source code files explicitly somewhere.

set(inkscape_SRC
attributes.h
attributes.cpp
...
version.cpp
version.h
)

These source files could be directly associated with an executable, but in Inkscape we compile most of the source code into an object library, using the '''add_library()''' function:

add_library(inkscape_base OBJECT ${inkscape_SRC})

This way we can create both the inkscape and inkview executables using the same core codebase, with CMake's '''add_executable()''':

add_executable(inkscape main.cpp $<TARGET_OBJECTS:inkscape_base>)
add_executable(inkview inkview.cpp $<TARGET_OBJECTS:inkscape_base>)

We also need to link external libraries into the mix, using '''target_link_libraries()''':

set(INKSCAPE_TARGET_LIBS inkscape nrtype_LIB croco_LIB avoid_LIB 2geom_LIB ...)

target_link_libraries(inkscape ${INKSCAPE_TARGET_LIBS})
target_link_libraries(inkview ${INKSCAPE_TARGET_LIBS})

Finally, we install the two executables via something like:

install(
PROGRAMS ${EXECUTABLE_OUTPUT_PATH}/inkscape
${EXECUTABLE_OUTPUT_PATH}/inkscape
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
)

== Inkscape's Build File Structure ==

To keep things manageable we split code out of CMakeLists.txt into more specialized files, whose logic all feeds back up to the top CMakeLists.txt. There are a few different ways this is done:

Our codebase is split into subdirectories containing various libraries and other collections of C++ files. We use CMake's '''add_subdirectory()''' to register each of these subdirs. CMake then recursively navigates into them, looks for a sub-CMakeLists.txt and then processes it.

The '''include()''' function is used to insert other CMake files as snippets into the current file. This can be handy for building up a collection of custom functions and macros. In Inkscape we typically place these into the CMakeScripts/ subdirectory and name the files with the *.cmake extension.

'''find_package()''' is critical for detecting and handling external dependencies, and deserves special mention. The first argument to this routine is the name of a dependency, which should correspond to a File<Dependency>.cmake file in the CMakeScripts/Modules/ directory.

So, to add a new dependency library Foo to Inkscape, you first must find or write a FindFoo.cmake file and put it at CMakeScripts/Modules/FindFoo.cmake. Then you use it like this:

find_package(Foobar)
if(FOOBAR_FOUND)
set(WITH_FOOBAR ON)
list(APPEND INKSCAPE_INCS_SYS ${FOOBAR_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${FOOBAR_LIBRARIES})
add_definitions(${FOOBAR_DEFINITIONS})
else()
set(WITH_FOOBAR OFF)
endif()

The exact logic will vary from dependency to dependency; review the Find<Dependency>.cmake file to see what variables it exports. For dependencies that are required, you use a REQUIRED parameter and can skip the check if its found (since cmake will bail if it isn't).

find_package(Baz REQUIRED)
list(APPEND INKSCAPE_INCS_SYS ${BAZ_INCLUDE_DIRS})
list(APPEND INKSCAPE_LIBS ${BAZ_LIBRARIES})
add_definitions(${BAZ_DEFINITIONS})

== Other Notable CMake Functions ==

Let's take a quick overview of a few of the other common function calls that you'll run across in Inkscape's CMake files.

'''configure_file()''' is a convenient way to process template files and substitute parameters in them with the values of variables within the cmake script. A common use would be to substitute the current release version number into C files or documentation, or to fill in configuration values into a config.h.in template.

'''option()''' lets you establish cmake options the user can use to control the build. This is typically used to allow the user to control whether to compile in various sub-modules or to specify alternate libraries.

'''add_custom_target()''' is used to create additional make targets, like 'make dist', 'make uninstall', 'make check', and so on. You can provide it with a separate CMake file to be executed, or simply list a sequence of COMMANDS for it to invoke.

add_definitions