From GridLAB-D Wiki
Jump to: navigation, search

 *** WORKING DRAFT *** 
Please review, edit and comment as necessary.


Dev:HowTo:Create a module - Developer's guide to creating a new module Template:NEW30

Developers can create new modules in GridLAB-D. This How To guide provides step-by-step instructions for creating a module that will run on all the supported platforms.

Overview

The process is generally as follows:

  1. Create a ticket to describe and track the status of the enhancement the module provides
  2. Create a working folder for the existing GridLAB-D code
  3. Create a module folder for the new module code
  4. Add the module to the solution files (varies by platform)
  5. Add the files for main.cpp, class implementation files, and other support files
  6. Set the compile and link options
  7. Compile, debug and test
  8. Commit working code to the repository
  9. Write wiki docs
  10. Validate across all platforms
  11. Notify project module is ready for release

External Components

Some modules require external components that are licenses separately from GridLAB-D. GridLAB-D allows different methods to include external components, depending on the license under which the component is distributed. As a general rule, any public domain or BSD-style license code may be included in GridLAB-D. Any other type of license is prohibited, include GPL and LGPL licenses.

The general guidelines are as follows:

Public domain
These may be included directly in the source code of GridLAB-D with not restrictions. These codes may be combined directly and/or intermingled with GridLAB-D sources without restrictions. It is strongly recommended that recognition of all public domain contributions be given for both technical and ethical reasons.
BSD-style and other open-source licenses that do not include "contamination" clauses
These codes may be included directly in the source code of GridLAB-D under the license terms. These codes should be included in separate source files with GridLAB-D sources in the third_party folder.
Open-source licenses that include "contamination" clauses (e.g., GPL, LGPL)
These codes may only be included in library form provided doing so does not contaminate GridLAB-D's BSD-style license with new license requirements. A tools repository folder is provided for all pre-compiled products that are optionally used by GridLAB-D. The installation of these codes on a user's system is done separately because they require separate user consent to the product's license agreement. GridLAB-D's installation program may offer to install some of these codes.
Proprietary code
Proprietary code may not be used in GridLAB-D unless specific written permission by the copyright holder to release the code into the open-source under GridLAB-D's BSD-style license. As the developer you are responsible for obtaining this permission and you should be prepared to demonstrate that you have obtained the copyright holder's permission when the GridLAB-D project team requests it.
Your code
If you are the author of the code you must use one of the above methods. We recommend using the GridLAB-D license, which is a BSD-style license.

If you have any questions or concerns, please contact the GridLAB-D project team.

Step-by-step Guides

In these guides the following conventions and variables are used for Linux/MacOSX users

SVN
This is the SVN repository URL. You can set this using the command
host% export SVN=https://gridlab-d.svn.sourceforge.net/svnroot/gridlab-d
WD
This is the working directory. You can set this using the command
host%  cd workdir
host% export WD=$(pwd)
module-name
A module name is a single complete lowercase word with no special characters, hyphens, underscores or digits. Do not use abbreviations, acronyms, etc. unless there is a compelling reason to do so. The name should be descriptive, e.g., an action, a process, a group, a concepts, or a product. Some examples of existing modules are:
Module naming convention
Action Process Grouping Concept Product
assert
optimize
control
debug
market
commercial
generators
network
climate
powerflow
reliability
mysql
tape
class-name
A class name is a simple or composite lowercase word with no special characters, digits or hyphens. Underscores are permitted. As a general rule acronyms etc. are not desirable. Class names should be description as a type or category of object with like properties and behaviors. Module may implement zero or more classes.
You will need permission to access the source code repository, these wiki pages and the TRAC system. Please contact the GridLAB-D project team to request access. In your email, be sure to explain why you need access and what you are planning to do.

Step 1 - Create a ticket

Create a new ticket by opening a new ticket. When you submit the ticket, it will be assigned a ticket id, which you will use to manage your work and coordinate with other collaborators and the GridLAB-D project team.

Step 2 - Create a working folder

Copy the trunk code into a new working branch:

host% svn copy $SVN/trunk $SVN/ticket/id

where id is the ticket number you received above.

Check out your working copy of the working branch:

host% cd $WD
host% svn checkout $SVN/ticket/id

Step 3 - Create the module folder

Create the new module folder

host% cd $WD
host% mkdir module-name

Step 4 - Add the module

Add the module to the working branch in the source repository

host% cd $WD
host% svn add name

Step 5 - Add the files

Create your working files. The following files are required

main.cpp
This is the main module implementation file.
Makefile.am
This is the linux/unix makefile.
module-name.vcproj
This is the Visual Studio makefile.

An easy way to start them as empty files is to use the touch command:

host% cd $WD/module-name
host% touch main.cpp Makefile.am module-name.vcproj

Add the new files to the repository

host% cd $WD/module-name
host% svn add main.cpp Makefile.am module-name.vcproj

For each class, you must create both the .cpp and the .h files for each class. See below for details on add classes.

Step 6 - Set the compile and link options

Linux/Unix systems
Edit the makefile for linux/unix system and add the following lines:
pkglib_LTLIBRARIES = module-name.la
module-name_la_SOURCES = \
       class-name1.cpp class-name1.h \
       class-name2.cpp class-name2.h \
          ... add other classes ...
       class-nameN.cpp class-nameN.h \
       main.cpp 
module-name_la_LDFLAGS = -module -no-undefined -avoid-version -version-info 1:0:0

uninstall-hook:
       -rmdir $(DESTDIR)$(pkglibdir)

Step 7 - Compile, debug and test

 TODO: 

Step 8 - Commit working code

You need to commit your working code if you are collaborating with others or you wish to share your progress, obtain assistance, and update the project team. When you are done, you must commit your code to the project for it to become available to others.

To commit your code, use the following command:

host% cd $WD
host% svn commit
... provide a brief description of your changes ...
... read the changeset number now ...

When you have obtained the changeset number, open the http://sourceforge.net/p/gridlab-d/tickets/ ticket for your work and update the status with the changeset number.

Step 9 - Write wiki docs

 TODO: 

Step 10 - Validate

 TODO: 

Step 11 - Notify project

 TODO: 

See also