Home

---

IMPORTANT NOTICE: As of 1/6/2020 slacgismo/gridlabd is no longer a fork of gridlab-d/gridlab-d.

---

HiPAS GridLAB-D Developer Guide

As of 11/13/19, this wiki is only for project administration and developers. The user manuals for HiPAS GridLAB-D are deployed at HiPAS GridLAB-D Documentation. This documentation uses the SLAC-Gismo Docs-Browser, which allows developers to manage the documentation of each branch separately.

Developer manuals, troubleshooting guides, and module guides are version specific and compiled when the application is build on a target host. You must start a web server instance on that target host to view those documents, e.g., using python3 -m http.server.

If you are looking for documentation for the PNNL versions of GridLAB-D, please use the ShoutWiki GridLAB-D Documentation.

Workflow overview

1. The master branch is the default branch.

• The develop branch is used for active development targeted for the next merge into master. Each update of master will receive the next patch number in in the current minor sequence, e.g., 4.2.n -> 4.2.(n+1)

• The minor branch is used for pull requests that are to be deployed to master with the next minor update, e.g., 4.n.x -> 4.(n+1)/.0. Minor updates are intended for significant new capabilities that are otherwise fully compatible with the existing version. Removal of deprecated capabilities is not permitted in a minor update.

• The major branch is used for pull requests that are to be deployed to master with the next major update, e.g., n.x.y -> (n+1).0.0. Major updates are intended for significant new capabilities that are incompatible with the existing version. Removal of deprecated capabilities is permitted in a major update provide the capability has been deprecated for at least one minor update.

2. Please make all changes in new or existing develop-* branches and submit a new Draft pull request to develop. Pull Requests must include a list of code, documentation, and validation changes.

• Code changes should be delivered using the current Coding guide.

• Documentation is maintained in the docs folder of the same branch in which the code changes are introduced. Documentation changes will be reviewed at the same time that code changes are reviewed after you submit your Draft pull request for review. See Documentation guide for details on writing docs for HiPAS GridLAB-D.

• Validation tests are delivered in autotest folders throughout the source tree. See Validation guide for details.

• Pull Requests to develop may be retargeted for minor or major by the project managers.

3. You may view the Pull Requests to determine the status of a branch. All branches are automatically validated using CircleCI and you may monitor validation progress at the CircleCI GridLAB-D Workflow or by viewing the status of the Pull Request. You may submit your Pull Request for review when it passes validation.

4. The master and develop branches are automatically built on Docker Hub. The resulting containers are stored in the GridLAB-D docker repositories. See Docker images for a list of the latest images for each major release.

5. Only the project administrators may tag master commits. These will by automatically tagged in Docker Hub at that time. Docker images are named after major power plants.

For additional details on workflows, see Workflows.

Developer System Setup

master

To build the master branch and any branch from master, you must first manually prepare your system (which is host dependent). For a rough guide see the build-aux/setup*.sh files of the develop branch.

If you have never installed HiPAS GridLAB-D on your system before, you will need to run the install script to prepare your system for development:

bash$ git clone http://source.gridlabd.us/ gridlabd
bash$ cd gridlabd
bash$ ./install.sh

This might take a few minutes. If it fails, you will have to consult the log to determine why, and fix the problem manually. If you want to force a manual build you can use the following command:

bash$ make -i system

At this time, not all platforms are supported, but the most common ones are, e.g., Mac OS X (Darwin), Linux (Oracle Linux, Ubuntu, Debian, and Amazon EC2). If you are using a different platform, please use the install script of the system that most closely resembles what you need. The install scripts are located in the build-aux folder and use the naming convention setup-<type>-<version>.sh. For developers, these scripts are fairly self-explanatory.

The regular rebuild process is usually the following:

bash$ make reconfigure && make -j30 system
bash$ gridlabd --version=install
<check the version>
bash$ gridlabd --validate
<check that it works ok>

develop

To download the development branch, use the following command:

bash$ git clone http://source.gridlabd.us/ -b develop gridlabd
bash$ cd gridlabd

If you plan to make changes to the code, creating a new branch is strongly advised, as the develop branch is protected:

bash$ git checkout -b develop-new-branch

after which you can safely make your changes.

To rebuild and install your code after making local changes, you should run the following command:

bash$ make reconfigure && make -j30 system

again, and running validation

bash$ gridlabd --validate

If you would like to use the system debugger, you can rebuild with debugging symbols enabled using the following command:

bash$ make reconfigure-debug && make -j30 system

Then you can use the debugger subcommand to load gridlabd in the system debugger, e.g.,

bash$ gridlabd [lldb|gdb] ...

where lldb is used for macOS system and gdb for Linux systems.

The develop version can manage multiple versions of HiPAS GridLAB-D on the same host running concurrently. For more information use the command

bash$ gridlabd version help