BUILD.Windows

Build On Windows

Table of Contents

 1. Introduction
 2. Using Microsoft Visual C++
     1. Version requirements
     2. Visual Studio Community
     3. Note before starting
 3. Install dependencies
 4. Build the GPlates application
     1. Configuring GPlates for building
     2. Build within Visual Studio
         1. Compiling GPlates
         2. Installing GPlates
     2. Build from the command line
         1. Compiling GPlates
         2. Installing GPlates
 5. Build the pyGPlates Python package
     1. Compiling and installing pyGPlates

Introduction

This is a guide to building GPlates or pyGPlates from source code in a Windows development environment.

Note: This source code originated from a "gplates" branch of the GPlates GitHub repository
      (https://github.com/GPlates/GPlates) and should only be used to compile GPlates (not pyGPlates).


Using Microsoft Visual C++

The Visual C++ set of development tools is part of the Microsoft Visual Studio
suite. More information can be found at https://visualstudio.microsoft.com/ - the 
product page for Visual Studio.


Version requirements

GPlates/pyGPlates can be built with Visual Studio Community 2019 (version 16) or newer.
As newer versions of Visual Studio are released, newer versions of the
dependencies will likely be required; if in doubt, for each dependency, download
the latest version instead of the version stated in DEPS.Windows.


Visual Studio Community

The Community edition of Visual Studio is freely available.
The steps for building GPlates/pyGPlates with the Community edition are the
same as those for the other editions (such as Professional edition).


Note before starting

For any activities requiring the command line, remember to use the developer command prompt shortcut
for your Visual Studio 64-bit compiler. These are available in the Windows "Start" menu in the folder
of your version of Visual Studio. For example, for Visual Studio 2019 you should see
"x64 Native Tools Command Prompt for VS 2019" under the "Visual Studio 2019" folder.
This starts a command prompt and sets up environment variables, allowing use of VC command line
applications (such as the compiler, linker, make and build tools).


Install dependencies

Firstly, you should ensure that you have installed all the dependencies.

See "DEPS.Windows" for more information on installing dependencies.

Note: The 'CMAKE_PREFIX_PATH' and 'PATH' environment variables are used to help find some of these libraries.


Build the GPlates application

Note: If you are compiling pyGPlates source code then refer to "Build the pyGPlates Python package".


Configuring GPlates for building

  1.  Run the CMake GUI program ("cmake-gui.exe").
  2.  Set the 'source' directory to the root source directory (the one that has 'src' as a sub-directory).
  3.  Set the 'build' directory to be the same as the 'source' directory for in-place builds or
      to a different directory for out-of-place builds (recommended for developers).
  4.  Click 'Configure'.
  5.  Specify your version of "Visual Studio" (such as "Visual Studio 16 2019") and specify "x64" as the
      platform for the generator. Note that the library dependencies should also be compiled as 64-bit.
  6.  Once configuration finished you should get no popup messages saying a dependency could not be found.
      If you do then you might need to edit 'CMAKE_PREFIX_PATH' environment variable if it is not referring
      to the correct dependency locations.
  7.  Even if no popup messages occurred, the 'Generate' will still be greyed out so you'll need
      to click 'Configure' once more.
  8.  Click 'Generate'.
      Note that starting with CMake 3.21 the 'generate' phase can take a long time.
  9.  The CMake GUI should then say 'Generating done' (or it might just close when finished).
  10. You should now have a "GPlates.sln" file in your root 'build' directory.

Once configured, you can build GPlates either within Visual Studio or from the command line.


Build within Visual Studio

This section covers compiling and installing GPlates from within Visual Studio.


Compiling GPlates

  1. Start Visual Studio.
  2. Open "GPlates.sln".
  3. Select the 'Release' build from the "Build->Configuration Manager..." menu.
  4. Right-click on 'gplates' in the "Solution Explorer" window and select 'Build'.
  5. There should now be "gplates.exe" in the "bin/Release" directory.


Installing GPlates

  1. Run the CMake GUI program ("cmake-gui.exe").
  2. Change the 'CMAKE_INSTALL_PREFIX' variable to the location you want to install to.
     Note that it defaults to "C:/Program Files/GPlates" which requires admin privileges.
  3. Click 'Configure' and 'Generate' (as covered in the 'Building' section).
  4. Start Visual Studio.
  5. Open "GPlates.sln".
  6. Select the 'Release' build from the "Build->Configuration Manager..." menu.
  7. Right-click on 'INSTALL' (under 'CMakePredefinedTargets') in the "Solution Explorer" window and select 'Build'.
  8. There should now be a "gplates.exe" in the directory specified by 'CMAKE_INSTALL_PREFIX'.
     Note that, unlike Linux, on Windows GPlates is installed as a standalone application.
     This means the dependency libraries are included along with "gplates.exe".


Build from the command line

This section covers compiling and installing GPlates from the command line.


Compiling GPlates

  1. Run the Visual Studio Command Prompt.
     * Click the Windows "Start" menu, open the folder containing your version of Visual Studio and
       run the 64-bit developer command prompt. For example, for Visual Studio 2019 you should see
       "x64 Native Tools Command Prompt for VS 2019" under the "Visual Studio 2019" folder.
  2. Go to the root 'build' directory (using "cd /d <build_dir>"). 
  3. Type the following on the command-line to build a release version of GPlates:
       msbuild gplates.sln /m /t:gplates /p:Configuration=Release /v:minimal
     ...where '/m' uses all CPUs, and '/t' specifies the target to build.
  4. There should now be "gplates.exe" in the "bin/Release" directory.


Installing GPlates

  1. Run the Visual Studio Command Prompt.
     * Click the Windows "Start" menu, open the folder containing your version of Visual Studio and
       run the 64-bit developer command prompt. For example, for Visual Studio 2019 you should see
       "x64 Native Tools Command Prompt for VS 2019" under the "Visual Studio 2019" folder.
  2. Go to the root 'build' directory (using "cd /d <build_dir>").
  3. Type the following on the command-line to install a standalone version of GPlates:
       cmake --install . --prefix <install_dir>
     ...where '<install_dir>' is your installation directory.
     Note: this assumes you've already built GPlates.
  4. There should now be a "gplates.exe" in the directory '<install_dir>'.
     Note that, unlike Linux, on Windows GPlates is installed as a standalone application.
     This means the dependency libraries are included along with "gplates.exe".


Build the pyGPlates Python package

Note: If you are compiling GPlates source code then refer to "Build the GPlates application".


Compiling and installing pyGPlates

  1. Run the Visual Studio Command Prompt.
     * Click the Windows "Start" menu, open the folder containing your version of Visual Studio and
       run the 64-bit developer command prompt. For example, for Visual Studio 2019 you should see
       "x64 Native Tools Command Prompt for VS 2019" under the "Visual Studio 2019" folder.
  2. Go to the root 'source' directory (the one that has 'src' as a sub-directory). 
  3. It's advisable to install into a Python environment.
     For example, to create and activate a Python 3.12 environment called 'my-env-name', type:

     py -3.12 -m venv my-env-name
     my-env-name\Scripts\activate.bat

    Note: This creates a local directory called 'my-env-name'. So you may instead want to
          specify an absolute path to a different location (outside the pyGPlates source code).

  4. Compile and install pyGPlates into the current Python environment by typing:

     python -m pip install .

     Note: In a Python environment you can just type 'pip install .'
           (ie, without prefixing with 'python -m').

A 'pygplates' Python package should now exist in the current Python environment.
In other words, running 'python -m pip list' should show 'pygplates' in the list.

Note: Python binary wheels can also be built for distribution to other computers.
      Please see 'pygplates/wheel/README.md' for more details.