GNOME.org
 

[gimp-web-devel/pat/bootstrap] content: update the Build for Windows page.

commit 08b0f0cdf4666b5ca5a6bc1b4a98162a89ab870a
Author: Jehan <jehan girinstud io>
Date:   Wed Sep 7 14:23:05 2022 +0200

    content: update the Build for Windows page.
    
    - Add a "Supported Windows API" section.
    - Add a "Copying our Continuous Integration scripts" section.
    - More markdown syntax fixes.
    - Some rewording here and there.
    - Add some notes on building with Microsoft tools and accepting patches
      for more build genericity.

 content/core/setup/build/Windows.md | 278 +++++++++++++++++++++++-------------
 1 file changed, 182 insertions(+), 96 deletions(-)
---
diff --git a/content/core/setup/build/Windows.md b/content/core/setup/build/Windows.md
index 411ae5d..ccc922b 100644
--- a/content/core/setup/build/Windows.md
+++ b/content/core/setup/build/Windows.md
@@ -7,35 +7,71 @@ weight: 3
 
 The main GIMP building instructions are at [Building GIMP](../). This page is for Windows-specific additions 
to that page.
 
-Note: the instructions are not always kept up to date. The primary development platform is the Debian 
Testing GNU/Linux distribution, so the very latest code from Git might not always build on other platforms.
+## Supported Windows API
 
+The supported versions of Windows are noted in the
+`devel-docs/os-support.txt` file in the respective branches:
 
-## Building GIMP natively under Windows using MSYS2
+* [OS support for GIMP 2.10 (stable
+  branch)](https://gitlab.gnome.org/GNOME/gimp/-/blob/gimp-2-10/devel-docs/os-support.txt)
+* [OS support for GIMP 2.99 (development
+  branch)](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/devel-docs/os-support.txt)
 
-Msys2 is a POSIX environment with basically everything you would find on a Linux system (shell, package 
manager, GCC…). It allows to use POSIX tools to build Windows softwares.
+Note that the GIMP project is really favoring backward compatibility as
+a general rule and we really don't like deprecating hardware when it is
+just a few years old. Nevertheless we may have to bump our Windows
+requirement when it becomes too hard to maintain.
 
+## Copying our Continuous Integration scripts
 
-### Setting up the environment
+Since our <abbr title="Continuous Integration">CI</abbr> build include
+Windows builds, and that we try to keep this build as full-featured and
+up-to-date as possible (because it is here to warn us of any new issue),
+a good practice could be to look at
+[.gitlab-ci.yml](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/.gitlab-ci.yml)
+file in our repository.
 
-First, '''follow the installation instructions''' for msys2 available at [https://msys2.github.io/ 
msys2.github.io].
+In particular, we have 2 pipelines for Windows:
 
-To open a terminal, you need to execute <code>msys2.exe</code> or <code>mingw64.exe</code>
+* For cross-compilation on Debian Testing for Windows, you should look
+  at the `build-image-w64` job for dependencies to install on Debian
+  from its package manager, at `deps-win64` for for the dependencies we
+  build ourselves with `crossroad` and at `gimp-win64` for compilation
+  of GIMP with `crossroad`.
+* For native MSYS2 compilation, you should look at `deps-win64-native`
+  for the dependencies to install with `pacman` and at
+  `gimp-win64-native` for compilation of GIMP.
 
-Update the system :
+Copying the commands run by these jobs might be all there is to do for
+you. To better understand the compilation flow, you may read below.
 
-<pre>pacman -Syyuu
-</pre>
+## Building GIMP natively under Windows using MSYS2
 
-If the shell tells you to close the terminal, close MSYS2 and run it again. That is a normal procedure.
+MSYS2 is a POSIX environment with basically everything you would find on
+a Linux system (shell, package manager, GCC…). It allows to use POSIX
+tools to build Windows software.
+
+### Setting up the environment
+
+1. First, follow the installation instructionsfor msys2 available at 
[msys2.github.io](https://msys2.github.io/).
+2. To open a terminal, you need to execute `msys2.exe` or `mingw64.exe`.
+3. Update the system :
+
+```sh
+ pacman -Syyuu
+```
+
+4. If the shell tells you to close the terminal, close MSYS2 and run it again. That is a normal procedure.
 
 
 ### Install the dependencies
 
-#### If you want to build gimp 2.10
+#### Stable branch (GIMP 2.10) dependencies
 
 If you have Windows 64bits:
 
-<pre>pacman -S --needed \
+```sh
+pacman -S --needed \
     base-devel \
     git \
     mingw-w64-x86_64-toolchain \
@@ -65,11 +101,12 @@ If you have Windows 64bits:
     mingw-w64-x86_64-SDL2 \
     mingw-w64-x86_64-suitesparse \
     mingw-w64-x86_64-xpm-nox
-</pre>
+```
 
 If you have Windows 32 bit:
 
-<pre>pacman -S --needed \
+```sh
+pacman -S --needed \
     base-devel \
     git \
     mingw-w64-i686-toolchain \
@@ -99,13 +136,14 @@ If you have Windows 32 bit:
     mingw-w64-i686-SDL2 \
     mingw-w64-i686-suitesparse \
     mingw-w64-i686-xpm-nox
-</pre>
+```
 
-#### If you want to build gimp master
+#### Unstable branch (GIMP 2.99) dependencies
 
 If you have Windows 64bits:
 
-<pre>pacman -S --needed \
+```sh
+pacman -S --needed \
     base-devel \
     git \
     mingw-w64-x86_64-toolchain \
@@ -140,11 +178,12 @@ If you have Windows 64bits:
     mingw-w64-x86_64-suitesparse \
     mingw-w64-x86_64-vala \
     mingw-w64-x86_64-xpm-nox
-</pre>
+```
 
 If you have Windows 32bits:
 
-<pre>  pacman -S --needed \
+```sh
+pacman -S --needed \
     base-devel \
     git \
     mingw-w64-i686-toolchain \
@@ -179,58 +218,68 @@ If you have Windows 32bits:
     mingw-w64-i686-suitesparse \
     mingw-w64-i686-vala \
     mingw-w64-i686-xpm-nox
-</pre>
+```
 
 Simply hit enter at the prompts for which packages to install (default=all). This step will download a ton 
of packages, and may take a while.
 
-
 ### Building the software
 
 You can now just follow the instruction on the main page [Building GIMP](../). Just be careful of the 
following changes:
 
-<pre>export GIMP_PREFIX=`realpath ~/gimp_prefix`
+```sh
+export GIMP_PREFIX=`realpath ~/gimp_prefix`
 export PATH="$GIMP_PREFIX/bin:$PATH"
 export PKG_CONFIG_PATH="$GIMP_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH"
 export PKG_CONFIG_PATH="$GIMP_PREFIX/share/pkgconfig:$PKG_CONFIG_PATH"
 export LD_LIBRARY_PATH="$GIMP_PREFIX/lib:$LD_LIBRARY_PATH"
-</pre>
+```
 
 * If you are on Windows 64bits, you need to add mingw64 on 32bits mingw32
 
-<pre>#environment variable for Autotools
+```sh
+# environment variable for Autotools
 export ACLOCAL_FLAGS="-I/c/msys64/mingw64/share/aclocal"
-#environment variable for introspection
+# environment variable for introspection
 export XDG_DATA_DIRS="$XDG_DATA_DIRS:$GIMP_PREFIX/share:/usr/local/share/:/usr/share/:/mingw64/share/"
-</pre>
-
+```
 
 You can add all the environment variable on `C:\msys64_or_msys32\home\{USERNAME}\.bash_profile` then run
 
-<pre>. .bash_profile
-</pre>
-
-
-
-* Disable docs for Babl : <code>-Dwith-docs=false</code> while calling Meson.
+```sh
+. .bash_profile
+```
 
-* Disable docs for Gegl : <code>-Ddocs=false</code> while calling Meson.
+* Disable docs for babl: `-Dwith-docs=false` while calling `meson`.
 
+* Disable docs for GEGL: `-Ddocs=false` while calling `meson`.
 
 You may want to disable the docs while building GIMP :
 
-
-* Meson build : <code>-Dgtk-doc=false -Dgtk-doc-app=false</code>
-* Autotools build : <code>--disable-docs</code>
+* meson build : `-Dgtk-doc=false -Dgtk-doc-app=false`
+* autotools build : `--disable-docs`
 
 ## Cross-Compiling GIMP under UNIX using crossroad
 
-A tool named [crossroad](https://pypi.python.org/pypi/crossroad)  has been developed to cross-build for 
Windows under Linux (it was even originally started to crossbuild GIMP specifically).
+A tool named [crossroad](https://pypi.python.org/pypi/crossroad)  has
+been developed to cross-build for Windows under Linux (it was even
+originally started to crossbuild GIMP specifically).
+
+Note that GObject-Introspection build (unstable branch only) is very
+hard when cross-compiling so it is usually disabled as an exception when
+a cross-compilation is detected. It is the only missing feature (binding
+such as Python, Lua, Vala…) for a cross-compiled GIMP.
+Yet some people manage to build the GObject-Introspection files, e.g.
+using `yocto`, which is why the `meson` configuration flag
+`-Dcan-crosscompile-gir=true` allows you to force GObject-Introspection
+build.
 
-See the [tutorial explaining how to build GIMP with 
it](http://girinstud.io/news/2016/05/crossroad-0-6-released-cross-building-gimp-as-an-example/).
+See the [tutorial explaining how to build GIMP with
+it](http://girinstud.io/news/2016/05/crossroad-0-6-released-cross-building-gimp-as-an-example/).
 
 Condensed, here is the process:
 
-<pre>crossroad w64 gimp-build
+```sh
+crossroad w64 gimp-build
 
 crossroad install \
     glib2-devel \
@@ -269,57 +318,67 @@ crossroad install \
     libwmf-devel \
     libgexiv2-devel headers
 
-git clone <a class="external free" href="git://git.gnome.org/babl" 
rel="nofollow">git://git.gnome.org/babl</a>
+git clone git://git.gnome.org/babl
 pushd babl
 crossroad configure
-make &amp;&amp; make install
+make && make install
 popd
 
-git clone <a class="external free" href="git://git.gnome.org/gegl" 
rel="nofollow">git://git.gnome.org/gegl</a>
+git clone git://git.gnome.org/gegl
 pushd gegl
 crossroad configure
-make &amp;&amp; make install
+make && make install
 popd
 
-git clone [https://github.com/mypaint/libmypaint.git https://github.com/mypaint/libmypaint.git]
+git clone https://github.com/mypaint/libmypaint.git
 cd libmypaint
 crossroad configure
-make &amp;&amp; make install
+make && make install
 popd
 
-git clone <a class="external free" href="git://git.gnome.org/gimp" 
rel="nofollow">git://git.gnome.org/gimp</a>
+git clone git://git.gnome.org/gimp
 crossroad configure --disable-python
-make &amp;&amp; make install
+make && make install
 popd
-</pre>
+```
 
 Check out the full tutorial for more details.
 
-Note: this is basically the same thing as the Mingw64 cross build, simply crossroad wraps all the 
complicated parts!
-
+*Note: this is basically the same thing as the MinGW-w64 cross build,
+simply crossroad wraps all the complicated parts!*
 
 ## Cross-Compiling GIMP under Linux using MinGW-w64
 
-Experience shows that working with the MinGW environment on a Linux machine provides a much faster 
compilation, and you are still able to compile for any Windows target (32 and 64 bits).
+Experience shows that working with the MinGW environment on a Linux
+machine provides a much faster compilation, and you are still able to
+compile for any Windows target (32 and 64 bits).
 
-NOTE: the following procedure should be distribution-independent and does not rely on your package 
management system, even though it uses some OpenSuse packages. It would probably work on OSX or any other 
UNIX as well (add a note on the list below if you know this procedure works on another OS).
+Notes:
 
-Has been known to work on at least: Linux Mint 15, Ubuntu 12.04LST and Mageia 2 distributions.
+* The same limitation with `GObject-Introspection` exist as for the
+  [crossroad build](#cross-compiling-gimp-under-unix-using-crossroad).
+* The following procedure should be distribution-independent and does
+  not rely on your package management system, even though it uses some
+  OpenSuse packages. It would probably work on OSX or any other UNIX as
+  well (add a note on the list below if you know this procedure works on
+  another OS).
 
-''Source of the original procedure from an [email by Victor 
Oliveira](https://mail.gnome.org/archives/gimp-developer-list/2012-May/msg00067.html).''
+Has been known to work on at least: Linux Mint 15, Ubuntu 12.04LST and
+Mageia 2 distributions.
 
+*The source of the original procedure comes from an [email by Victor
+Oliveira](https://mail.gnome.org/archives/gimp-developer-list/2012-May/msg00067.html).*
 
 ### Install mingw-w64
 
-This procedure relies on the newer [http://mingw-w64.sourceforge.net/ MinGW-w64] project.
+This procedure relies on the newer [MinGW-w64](http://mingw-w64.sourceforge.net/)  project.
 
-If your distribution provides the <code>mingw-w64</code> tools, you may install them with your package 
manager.
+If your distribution provides the `mingw-w64` tools, you may install them with your package manager.
 
-Otherwise, download directly the last release 
[https://sourceforge.net/projects/mingw-w64/files/mingw-w64/mingw-w64-release on Sourceforge].
+Otherwise, download directly the last release [on 
Sourceforge](https://sourceforge.net/projects/mingw-w64/files/mingw-w64/mingw-w64-release).
 
 The archive contains a prefix tree, that you can consider as read-only (just like your linux system).
 
-
 ### Install GIMP Dependencies
 
 The default environment provided by MinGW does not have the huge list of dependencies that GIMP requires.
@@ -328,10 +387,11 @@ Fortunately the [email](https://mail.gnome.org/archives/gimp-developer-list/2012
 
 From the root of your cross-compiling prefix (`$HOME/w64`) run:
 
-<pre>bash grab-stuff.sh
-</pre>
+```sh
+bash grab-stuff.sh
+```
 
-You will notice in particular a new usr/ folder, and inside i686-w64-mingw32/ and x86_64-w64-mingw32/ 
sub-folders.
+You will notice in particular a new `usr/` folder, and inside `i686-w64-mingw32/` and `x86_64-w64-mingw32/` 
sub-folders.
 
 TODO : Make a proper dependency list.
 
@@ -339,37 +399,42 @@ TODO : Make a proper dependency list.
 
 Define the environment variables as described in [[Hacking:Building]]. You may also need to reset pkg-config:
 
-<pre>export PKG_CONFIG_LIBDIR=
-</pre>
+```sh
+export PKG_CONFIG_LIBDIR=
+```
 
 ### Build BABL
-<pre>git clone <a class="external free" href="git://git.gnome.org/babl" 
rel="nofollow">git://git.gnome.org/babl</a>
+
+```sh
+git clone <a class="external free" href="git://git.gnome.org/babl" 
rel="nofollow">git://git.gnome.org/babl</a>
 cd babl
 ./autogen.sh --prefix=$PREFIX --host=$HOST --enable-introspection=no
 make
 make install
-</pre>
+```
 
 ### Build GEGL
-<pre>git clone <a class="external free" href="git://git.gnome.org/gegl" 
rel="nofollow">git://git.gnome.org/gegl</a>
+
+```sh
+git clone <a class="external free" href="git://git.gnome.org/gegl" 
rel="nofollow">git://git.gnome.org/gegl</a>
 cd gegl
 ./autogen.sh --prefix=$PREFIX --host=$HOST --enable-introspection=no --disable-docs --disable-glibtest
 make
 make install
-</pre>
+```
 
 ### Build any optional dependency
 
 This step is not necessary if you compile GIMP with the minimum set of dependency as indicated at the next 
section.
 
-
 #### Compression support
 
 Nevertheless if for instance, you needed compression support (hence be able to load and save your images in 
various compressed format), you would need zlib,libbzip2 and liblzma installed. In particular the 
cross-compilation environment described on this page has no pre-compiled liblzma. You would need to 
cross-compile it first yourself.
 
-In my case xz-5.0.4 worked well.
+In my case `xz-5.0.4` worked well.
 
-<pre>cd ..
+```sh
+cd ..
 wget [http://tukaani.org/xz/xz-5.0.4.tar.xz http://tukaani.org/xz/xz-5.0.4.tar.xz]
 tar xf xz-5.0.4.tar.xz
 rm xz-5.0.4.tar.xz
@@ -377,30 +442,40 @@ cd xz-5.0.4
 ./configure --prefix=$PREFIX --host=$HOST
 make
 make install
-</pre>
+```
 
-Finally obviously in the GIMP configure step, remove the ''--without-liblzma'' option on the autogen.sh 
command line before compiling GIMP.
+Finally obviously in the GIMP configure step, remove the `--without-liblzma` option on the `autogen.sh` 
command line before compiling GIMP.
 
 You should be able to do similar things for other optional features that you would want on your 
cross-compiled GIMP.
 
-Alternatively there exists a [http://eternallybored.org/misc/gimp/configrue-libbz2.patch patch] to get 
compression support working in 32 bit builds.
-
+Alternatively there exists a [patch](http://eternallybored.org/misc/gimp/configrue-libbz2.patch)  to get 
compression support working in 32 bit builds.
 
 #### Multi-Language support
 
-Multi-Language support is installed with the grab-stuff.sh script. Due to a bug in the package 
mingw32-iso-codes-devel the pkgconfig program can't find the iso-codes package.
-In this case you will notice, that GIMPs autogen.sh reports
+Multi-Language support is installed with the `grab-stuff.sh` script. Due
+to a bug in the package `mingw32-iso-codes-devel` the pkgconfig program
+can't find the `iso-codes` package. In this case you will notice, that
+GIMPs `autogen.sh` reports:
 
+```sh
 Language selection:  no
+```
 
-and the finished GIMP build has no language selector listbox in ''Edit/Preferences/Interface''.
-To solve this, copy ''$HOME/w64/usr/$HOST/sys-root/mingw/share/pkgconfig/iso-codes.pc'' to 
''$HOME/w64/usr/$HOST/sys-root/mingw/lib/pkgconfig'' before executing autogen.sh or configure for GIMP.
-Note you have to do this for every value of $HOST you want to build (e.g. i686 and x86_64 architecture).
-Also merge the MinGW and GIMP build folders when installing it on Windows (see the <a 
href="#Troubleshooting"> Troubleshooting section</a>).
+and the finished GIMP build has no language selector listbox in `Edit/Preferences/Interface`.
+To solve this, copy
+`$HOME/w64/usr/$HOST/sys-root/mingw/share/pkgconfig/iso-codes.pc` to
+`$HOME/w64/usr/$HOST/sys-root/mingw/lib/pkgconfig` before executing
+`autogen.sh` or `configure` for GIMP.
 
+Note you have to do this for every value of `$HOST` you want to build
+(e.g. `i686` and `x86_64` architecture).
+Also merge the MinGW and GIMP build folders when installing it on
+Windows (see the [Troubleshooting section](#troubleshooting)).
 
 ### Build GIMP
-<pre>cd ..
+
+```sh
+cd ..
 git clone <a class="external free" href="git://git.gnome.org/gimp" 
rel="nofollow">git://git.gnome.org/gimp</a>
 cd gimp
 ./autogen.sh  --prefix=$PREFIX  --host=$HOST \
@@ -415,18 +490,19 @@ cd gimp
     --without-libzma \
 make
 make install
-</pre>
+```
 
 ### Install On Windows
 
-To test your compiled installation, I found nothing better than moving the whole tree (in my case $HOME/w64) 
into Windows, because libraries are dynamically linked, then run $HOME/w64/bin/gimp-2.9.exe under Windows.
+To test your compiled installation, I found nothing better than moving
+the whole tree (in my case `$HOME/w64`) into Windows, because libraries
+are dynamically linked, then run `$HOME/w64/bin/gimp-2.9.exe` under
+Windows.
 
 If you really want to build a self contained GIMP, you should compile everything as static libraries.
-GIMP will probably still rely on some external files though, for instance what you find under 
$HOME/w64/share/gimp/2.0/. Maybe other things. But this will have to be tested if needed.
-
-
-
-
+GIMP will probably still rely on some external files though, for
+instance what you find under `$HOME/w64/share/gimp/2.0/`. Maybe other
+things. But this will have to be tested if needed.
 
 ### Troubleshooting
 
@@ -521,21 +597,31 @@ Replace the line <code><include ignore_missing="yes">$a_directory/conf.d</includ
 ## Building GIMP using Microsoft tools
 
 Microsoft Visual Studio comes with its own C compiler.
-Most of GIMP development is done with the GCC and its MinGW Windows port.
+Most of GIMP development is done with `GCC` and its `MinGW` Windows
+port, or `Clang`.
 
 Unfortunately both are not fully compatible, so integrating GCC into the
 Visual Studio build chain has its flaws, even while it might work in some points.
 
-Because of this you are recommended to use MinGW for building GIMP on Windows.
-
+Because of this you are currently recommended to use MinGW for building
+GIMP on Windows. Eventually we are for more genericity and are therefore
+not against a build working on more compilers. If you wish to contribute
+fixes to make GIMP build with Microsoft Visual Studio, then maintain the
+build, you are welcome to contribute.
 
 ## Building GIMP plug-ins using Microsoft tools
 
-[http://web.archive.org/ How to build a GIMP plug-in with Visual Studio] (archive.org link salvaged, 
original link, now broken, was: [http://registry.gimp.org/node/24883 http://registry.gimp.org/node/24883])
+An old tutorial existed on the former registry (salvaged through
+`archive.org`) explaining how to build plug-ins using Microsoft tools:
+[How to build a GIMP plug-in with Visual 
Studio](https://web.archive.org/web/20150906090521/http://registry.gimp.org/node/24883)
 
+It might not be completely outdated, since plug-ins are a lot easier to
+compile than GIMP itself.
 
 ## Packaging third-party GIMP plug-ins for Windows
 
-Users on the Windows and Mac OSX platforms expect software to be packaged in a self-installing file (an 
installer).  Even though GIMP plugins (whether scripts in Python or Scheme, or executables in the C language) 
are relatively easy to install, you might want to package them using an installer such as 
[http://www.jrsoftware.org/isinfo.php Inno Setup].
-
-
+Users on the Windows and Mac OSX platforms expect software to be
+packaged in a self-installing file (an installer). Even though GIMP
+plug-ins (whether scripts in Python or Scheme, or executables in the C
+language) are relatively easy to install, you might want to package them
+using an installer such as [Inno Setup](http://www.jrsoftware.org/isinfo.php).
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]