Building Guide

This build guide is intended for developers who will be frequently building and debugging multiple versions of HiPAS GridLAB-D on their systems.

Build files and Folders

HiPAS GridLAB-D uses autotools to configure and build gridlabd. Aside from the required build files Makefile.am and configure.ac a number of ancillary files and folders are also used during the configure and make processes.

Build support folders

• .github/: This folder contains the files needed by GitHub to run automated actions. It also contains the issues template.

• build_aux/: This folder contains a version identification script use by make and platform-specific setup scripts used by install.sh.

• docker/: This folder contains the files need to build docker images.

• `m4/': This folder contains the autom4te files needed to build required libraries and packages, including SuperLU, Xerces, Doxygen, Pthread, and Curses.

• third_party/: This folder contains the third-party libraries needed to build gridlabd.

• utilities/: This folder contains support utilities used by configure and make to build gridlabd.

Build support files

• am include.mk: This file contains automake rules for components in GridLAB-D.

• checkpkgs: This script is used to verify that the directories list in Makefile.am are ready for use by autoreconf.

• configure.ac: This file is the main autoconf configuration control file for GridLAB-D.

• configure.opt: This file contains the default configuration options used when running configure.

• custom.mk: The file contains the list of optional modules enabled when building GridLAB-D.

• customize: This script controls the options used by the configure script.

• gldmake: This script provides a shell menu-based build environment.

• gridlabd.spec.in: This file contains the configure specification for the GridLAB-D application

• install.conf-default: This file contains the default options for the install.sh setup script.

• install.sh: This script is used to install GridLAB-D on a new system.

• Makefile.am: This file contains the main makefile template for GridLAB-D.

• modules.mk: This file contains a list of the modules that must be built for a complete GridLAD-B installation

• requirements.txt: This file contains the Python modules and versions required by GridLAB-D.

Other build files

• .../Makefile.mk: Many folders include Makefile.mk which will be consulted when make is run.

• .../requirements.txt: All files named requirements.txt will be consulted when python is updated.

Make targets

There are many targets support by make. To get a comprehensive list, use make help. The most important targets are the following:

• install: This target installs gridlabd in the target folder. By default, the target folder is /usr/local/opt/gridlabd/VERSION-BUILD-BRANCH. Use the --prefix=FOLDER to change the target folder.

• system: This target install gridalbd in the target folder and link the system files to that target so all users will have access to it from the /usr/local/bin/gridlabd.

• clean: This target removes all the intermediate files created during a build.

• clean-wc: This target removes all the untracked files in the source tree.

• reconfigure: This target regenerates and runs the configure file after the branch name has changed. This is necessary before using make system to avoid target folder inconsistencies due to the change in the branch name.

Selecting versions and platforms

HiPAS GridLAB-D includes a version control subcommand that allow developers to quickly change the version in use by the local host.

• Show the current version: gridlabd version show

• Obtain a list of installed versions: gridlabd version list

• Set the version for the system: gridlabd version set NAME

• Remove a version from the system: gridlabd version delete NAME

In addition, the docker subcommand can be used to enable the use of a docker image instead of the locally installed build. When a docker image tag name gridlabd exists, then the local gridlabd will use the docker image instead of the local install.

• To enable a docker image: gridlabd docker enable NAME

• To disable a docker image: gridlabd docker disable

• To determine the docker image status: gridlabd docker status

Pro-tip

When developing code in docker images you can map your local host's files in the source volume in the docker container. For example, you can clone the repository on your local host:

$ git clone https://source.gridlabd.us/ -b develop gridlabd

This allows you to edit and do git operation on your local host.

Then you can start the docker container to build and test the system:

$ docker run -it -v $PWD/gridlabd:/usr/local/src/gridlabd slacgismo/gridlabd:latest bash
# cd /usr/local/src/gridlabd
# export MAKEFLAGS=-j$(nproc)
# autoreconf -isf && ./configure && make system
...
# gridlabd -T 0 --validate
...

If you want to test installs from scratch, the do the following:

$ docker run -it -v $PWD/gridlabd:/usr/local/src/gridlabd BASEIMAGE bash
# cd /usr/local/src/gridlabd
# ./install.sh -v
...

where BASEIMAGE is the desired docker base container image, e.g., debian:10, ubuntu:20_04.