Skip to content

05. Developers

Jump to bottom
A.D. Letaw edited this page Sep 7, 2017 · 1 revision

Developers Guide

Gmacs source files are publicly available and open source. Anyone interested in modifying the software for their own purposes may do so freely with attribution. Those interested in contributing to the Gmacs project should fork the repository and make contributions to the source by initiating pull requests. The Gmacs core development team will review all pull requests and accept useful and compatible contributions.

The following information is intended to help new developers get started and adopt a standardized approach to development of the Gmacs source code. Experienced developers and GitHub users may wish to Fork, Clone, establish the necessary Remotes, and start following the Gmacs Development Workflow. If those terms are new to you, please read the Github Guides and the following:

We recommend using the clang++ compiler. This can be downloaded from the terminal on a ubuntu machine using

sudo apt-get update
sudo apt-get install clang-3.5

Set up a symbolic link using

sudo ln -s /usr/bin/clang-3.5 /usr/bin/clang
sudo ln -s /usr/bin/clang++-3.5 /usr/bin/clang++

Forking Gmacs

Forking Gmacs on Github will copy the entire repository and its full version history to your Github user account. If you do not already have a Github account, you can sign up for one on the Github main page. To fork the repository, simply navigate to the Gmacs Homepage and click the Fork button in the top right hand corner of the main page. This will create a new repository at your Github address of the form https://github.com/username/gmacs. Forked repositories automatically link to their upstream host, that is, they remain connected with the Gmacs master repository. Your membership of the Gmacs project will be publicly displayed on the Gmacs Contributors page, and accepted contributions will be recorded as part of the master repository and its associated version history.

Cloning Source Files

Open your Git Bash client or preferred method for interacting with Git and navigate to a parent directory where you wish to establish a gmacs subdirectory. Then follow these steps:

Enter git clone https://github.com/username/gmacs.git

Navigate to the newly created gmacs subdirectory and enter:

git remote add seacode https://github.com/seacode/gmacs.git

Check you have a remote link to your upstream Gmacs repository as well as a separate remote link to the Gmacs master repository. Enter the following command:

git remote -v

You should see the following:

origin https://github.com/username/gmacs.git (fetch)
origin https://github.com/username/gmacs.git (push)
seacode https://github.com/seacode/gmacs.git

Development Workflow

In order to contribute usefully to the Gmacs project, developers should follow this workflow:

  1. Perform a Git Pull to ensure you have the latest development source files:
  • git pull seacode
  1. Create a new branch named after your intended new feature, e.g.
  • git checkout -b newfeature
  1. Edit source files in your local version of the Gmacs repository
  2. Build Gmacs and test the demonstration examples and/or your own models
  3. Commit your changes to Git:
  • git add file.ext
  • git commit -m "commit message"
  • Be sure to include a descriptive commit message
  1. Push changes to your personal Remote on Github:
  • git push origin
  1. Submit a Pull Request

See this handy Guide to Contributing for more tips.

If the development version of Gmacs gets updated, you may want to integrate these changes into your branch. This can be done using the command git merge origin/develop.

Modifying Source Files

The main source code for Gmacs, as with any ADMB-based program, is the .tpl file. The gmacs.tpl file is located in the gmacs/src directory. The code is structured according to common ADMB conventions, and commented with Doxygen comments to facilitate the development of a Gmacs Application Programming Interface (API).

Contributing developers should maintain consistency with the existing code style and comment new code with Doxygen style comments and in-line comments.

Compare Mode

GitHub provides useful tools for making comparisons between different branches or commits of Gmacs. To enter compare mode simply add /compare to the end of the Gmacs online repository (i.e. type https://github.com/seacode/gmacs/compare).

Debugging

From linux the debugging software gdb can be used, see the gdb quick start guide here: http://web.eecs.umich.edu/~sugih/pointers/gdbQS.html.

gdb gmacs
set args -nox -iprint 50
run

Gmacs: A Stock Assessment Modeling Framework

Clone this wiki locally