From GridLAB-D Wiki
Jump to: navigation, search

Ostrander (Version 5.0)  New in 5.0! 

Building GridLAB-D

Prerequisites

These instructions should be executed in your terminal of choice. This may be MSYS2, a WSL instance, or the built-in terminal for your OS of choice (note: Windows CMD does not work).

If you are on Windows and are using MSYS2, see this page for setting up MSYS2 to run the commands below.

If you have an Apple-ARM-based Mac, be sure to skip to the ARM-Based Section for those instructions.

Packages

CMake  
CCMake or CMake-gui (optional)   
g++ or Clang

Installation

Git

Clone the git repository for GridLAB-D and update submodules:

git clone https://github.com/gridlab-d/gridlab-d.git
cd gridlab-d
git submodule update --init

Prepare out-of-source build directory

Create build directory and move into it:

mkdir cmake-build
cd cmake-build

Generate the build system

CMake flags can be added using the `-D` prefix, and different build systems can be selected using `-G`.

Below is a general format guide, and an actual viable build command for most platforms.

# Format:
cmake <flags> ..
# Full Example: 
cmake -DCMAKE_INSTALL_PREFIX=~/software/GridLAB-D -DCMAKE_BUILD_TYPE=Release -G "CodeBlocks - Unix Makefiles" ..

Build and install the application

CMake can directly invoke the build and install process by running the below command. Multiprocess build is enabled through the `-j#` flag (`-j8` in the included example).

# Run the build system and install the application
cmake --build . -j8 --target install

CMake Variables

The following variables affect the build process and can be changed using the `-D` flag at build generation or by updating the cache using ccmake or cmake-gui (default values are shown).

Variable Valid Values Description Linux/Mac Default Windows Default
Example Example Example Example Example
CMAKE_BUILD_TYPE 'Debug', 'RelWithDebInfo', 'MinSizeRel', 'Release' Compiler optimizer configuration Debug Debug
CMAKE_INSTALL_PREFIX Any path Install location /usr/local %ProgramFiles%
GLD_USE_HELICS ON/OFF Enables detection and use of HELICS OFF OFF
HELICS_DIR Any path Hint indicating HELICS install directory
GLD_USE_MYSQL ON/OFF Enables detection and use of MySQL OFF OFF
MYSQL_DIR Any path Hint indicating MySQL install directory

Enable building with HELICS

To enable HELICS set the `GLD_USE_HELICS` flag to `ON` if HELICS is in a custom path set `HELICS_DIR` to the install location in CMake or as an environmental variable

GLD_USE_HELICS=OFF

Enable building with MySQL

To enable MySQL support set the `GLD_USE_MYSQL` flag to `ON` if MySQL is in a custom path set `MYSQL_DIR` to the install location in CMake or as an environmental variable

Enable build debugging

To output all build commands during build, set following flag to `ON`

CMAKE_VERBOSE_MAKEFILE=OFF

Developer Build Flags

GridLAB-D Developers may want to enable additional C++ code style and bugprone checks, which have been made available through the use of the clang-tidy tool at compile time. To enable these build-time checks, a flag to enable these checks is provided

GLD_USE_CLANG_TIDY=ON

WARNING: Enabling clang-tidy checks will significantly increase the number of build warnings for portions of the code base which have not yet been updated

Building on ARM-Based macOS (M1, M2, M3....)

As of this writing (Sept 2024), GridLAB-D functions best when built as a x86-64 (Intel-chip) binary where macOS can use Rosetta 2 to translate the machine code to run on an ARM-based processor.

Switch the architecture of the Terminal shell

gld_user2@mymac ~ % arch -x86_64 zsh

This launches a new zsh shell as an x86-64 process so the compilation/build run in this shell will produce x86-64 binary.

Install HomeBrew

Homebrew is a package manager for macOS and is the easiest way to install many tools from the Linux world. As of this writing (Sept 2024), you can install Homebrew with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install build dependencies

brew install cmake # installs cmake and ccmake

Optionally, if you plan on including HELICS compatibility in GridLAB-D, install the ZeroMQ library

brew install zeromq

(HELICS-only) Find the location of the HELICS library file libhelics.dylib

Depending on how you installed HELICS (building from source, installing pre-built binaries, using `pip`) the location of the libhelics.dylib on your system will vary. If you did install via `pip` you can use

pip show helics

as a starting point for your search. Other good places to look include `/usr/lib`, `/usr/local/lib`.

Once you find libhelics.dylib, copy the path to the folder containing it as it will be needed in configuring the build.

Clone in the GridLAB-D repo and set up the build directory (as in above instructions)

No special macOS instructions, here. The next step comes when configuring the build by running

ccmake .

Configure the build

The following environment variables are the most likely ones you may want to change:

CMAKE_INSTALL_PREFIX = <<Location in which to install. If in a virtual or conda environment you'll want to set this to the path used in that environment.>>
GLD_HELICS_DIR = <<Directory where libhelics.dylib resides.>>
GLD_USE_HELICS = ON
GLD_HELICS_DIR = <<Directory where libhelics.dylib resides.>>

Once all of these have been set, press `c` to configure and `g` to generate the configuration file. Due to a bug in ccmake it may take multiple attempts with `c` to get the `g` option to appear

Build and install (as in above instructions)