Dev:Example 1

Developer Example 1 - Creating a module

This example is based loosely on the assert module.

The purpose of an assert object is to verify that a particular property of an object meet certain criteria. This can be done by testing the property at the end of each timestep.

Note

Because we do not want our assert object to conflict with the existing assert object we will create a new module called example.

Files

The following files need to be modified or created.

configure.ac

AC_CONFIG_FILES([ ./Makefile \
  core/Makefile \
  core/rt/Makefile \
  ...
  example/Makefile \
  gridlabd.spec \
  ])

Makefile.am

SUBDIRS = . third_party/CBLAS third_party/superLU_MT core ... \
  ... \
  ... example

example/Makefile.am

pkglib_LTLIBRARIES = example.la
example_la_SOURCES = main.cpp
example_la_LDFLAGS = -module -no-undefined -avoid-version -version-info 1:0:0

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

Warning

Makefiles are very picky—the spaces before -rmdir are a tab separator not 8 spaces.

example/main.cpp

/// $Id$
/// Copyright (c) 2013, Example
/// @file main.cpp
/// @addtogroup example Example module
#define DLMAIN
#include "gridlabd.h"
// TODO add class includes here
// TODO define globals here
EXPORT CLASS *init(CALLBACKS *fntable, MODULE *module, int argc, char *argv[])
{
  if ( set_callback(fntable)==NULL )
  {
     errno = EINVAL;
     return NULL;
  }
  // TODO register globals here
  // TODO register classes here
  return NULL; // TODO return first class registered
}
EXPORT int do_kill(void*) { return 0; }
// TODO add optional functions here

example/example.vcproj

If you have VS2005 then create a new project and apply the following settings to the four primary configurations (debug/release win32/x64):

VS2005 Project Settings for new modules

General
Output Directory	..\VS2005\$(PlatformName)\$(ConfigurationName)
Intermediate Directory	$(PlatformName)\$(ConfigurationName)
Extensions to Delete on Clean	*.obj;*.ilk;*.tlb;*.tli;*.tlh;*.tmp;*.rsp;*.pgc;*.pgd;$(TargetPath)
Configuration Type	Dynamic Library (.dll)
Debugging
Command	($OutDir)gridlabd.exe
Command Arguments	--libinfo $(TargetName)
Working Directory	..
C/C++
General
Additional Include Directories	../core
Debug Information Format	Program Database (/Zi)
Warning Level	Level 3 (/W3)
Detect 64-bit Portability Issues	Yes (/Wp64)
Optimization
Optimization (Release only)	Maximum Speed (/O2)
Optimization (Debug only)	Disabled (/Od)
Preprocessor
Preprocessor Definitions	WIN32;_DEBUG;_WINDOWS;_USRDLL;_CRT_SECURE_NO_DEPRECATE;_TESTING
Code Generation
Enable Minimal Rebuild (Debug only)	Yes (/Gm)
Basic Runtime Checks (Debug only)	Both (/RTC1, equiv. to /RTCsu)
Runtime Library (Debug only)	Multi-threaded Debug DLL (/MDd)
Runtime Library (Release only)	Multi-threaded (/MT)
Precompiled Headers
Create/Use Precompiled Header	Not Using Precompiled Headers
Advanced
Disable Specific Warnings	4996
Linker
General
Output File	$(OutDir)\$(ProjectName).dll
Enable Incremental Linking (Release only)	No (/INCREMENTAL:NO)
Enable Incremental Linking (Debug only)	Yes (/INCREMENTAL:YES)
Additional Library Directories	$(OutDir);$(SolutionDir)$(PlatformName)\$(ConfigurationName)
Debugging
Generate Debug Info (Debug only)	Yes (/DEBUG)
System
Subsystem	Windows (/SUBSYSTEM:WINDOWS)
Advanced
Target Machine (x64 only)	MachineX64 (/MACHINE:X64)
Target Machine (win32 only)	MachineX86 (/MACHINE:X86)

Don't forget to add the main.cpp file to the new project.

If you do not have VS2005 then you must manually create this file. Note that there are several instances of <<<GUID>>> in the example for each of which you must generate your own GUID.

<?xml version="1.0" encoding="Windows-1252"?>
<VisualStudioProject
	ProjectType="Visual C++"
	Version="8.00"
	Name="example"
	ProjectGUID="{<<<GUID>>>}"
	RootNamespace="gridlabd"
	Keyword="Win32Proj"
	>
	<Platforms>
		<Platform Name="Win32" />
		<Platform Name="x64" />
	</Platforms>
	<ToolFiles>
	</ToolFiles>
	<Configurations>
		<Configuration
			Name="Debug|Win32"
			OutputDirectory="..\VS2005\$(PlatformName)\$(ConfigurationName)"
			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)\$(ProjectName)"
			ConfigurationType="2"
			CharacterSet="2"
			DeleteExtensionsOnClean="*.obj;*.ilk;*.tlb;*.tli;*.tlh;*.tmp;*.rsp;*.pgc;*.pgd;$(TargetPath)"
			>
			<Tool Name="VCPreBuildEventTool" />
			<Tool Name="VCCustomBuildTool" />
			<Tool Name="VCXMLDataGeneratorTool" />
			<Tool Name="VCWebServiceProxyGeneratorTool" />
			<Tool Name="VCMIDLTool" />
			<Tool Name="VCCLCompilerTool"
				Optimization="0"
				AdditionalIncludeDirectories="..\core;"
				PreprocessorDefinitions="WIN32;_DEBUG;_WINDOWS;_USRDLL;_CRT_SECURE_NO_DEPRECATE;_TESTING"
				MinimalRebuild="true"
				BasicRuntimeChecks="3"
				RuntimeLibrary="3"
				UsePrecompiledHeader="0"
				WarningLevel="3"
				Detect64BitPortabilityProblems="true"
				DebugInformationFormat="4"
				DisableSpecificWarnings="4996"
			/>
			<Tool Name="VCManagedResourceCompilerTool" />
			<Tool Name="VCResourceCompilerTool" />
			<Tool Name="VCPreLinkEventTool" />
			<Tool Name="VCLinkerTool"
				LinkIncremental="2"
				AdditionalLibraryDirectories="$(OutDir)"
				GenerateDebugInformation="true"
				SubSystem="2"
				TargetMachine="1"
			/>
			<Tool Name="VCALinkTool" />
			<Tool Name="VCManifestTool" />
			<Tool Name="VCXDCMakeTool" />
			<Tool Name="VCBscMakeTool" />
			<Tool Name="VCFxCopTool" />
			<Tool Name="VCAppVerifierTool" />
			<Tool Name="VCWebDeploymentTool" />
			<Tool Name="VCPostBuildEventTool" />
		</Configuration>
		<Configuration
			Name="Debug|x64"
			OutputDirectory="..\VS2005\$(PlatformName)\$(ConfigurationName)"
			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)\$(ProjectName)"
			ConfigurationType="2"
			CharacterSet="2"
			DeleteExtensionsOnClean="*.obj;*.ilk;*.tlb;*.tli;*.tlh;*.tmp;*.rsp;*.pgc;*.pgd;$(TargetPath)"
			>
			<Tool Name="VCPreBuildEventTool" />
			<Tool Name="VCCustomBuildTool" />
			<Tool Name="VCXMLDataGeneratorTool" />
			<Tool Name="VCWebServiceProxyGeneratorTool" />
			<Tool Name="VCMIDLTool"
				TargetEnvironment="3"
			/>
			<Tool Name="VCCLCompilerTool"
				Optimization="0"
				AdditionalIncludeDirectories="..\core;"
				PreprocessorDefinitions="WIN32;_DEBUG;_WINDOWS;_USRDLL;_CRT_SECURE_NO_DEPRECATE;_TESTING"
				MinimalRebuild="true"
				BasicRuntimeChecks="3"
				RuntimeLibrary="3"
				UsePrecompiledHeader="0"
				WarningLevel="3"
				Detect64BitPortabilityProblems="true"
				DebugInformationFormat="3"
				DisableSpecificWarnings="4996"
			/>
			<Tool Name="VCManagedResourceCompilerTool" />
			<Tool Name="VCResourceCompilerTool" />
			<Tool Name="VCPreLinkEventTool" />
			<Tool Name="VCLinkerTool"
				LinkIncremental="2"
				AdditionalLibraryDirectories=""$(OutDir)";"$(SolutionDir)$(PlatformName)\$(ConfigurationName)""
				GenerateDebugInformation="true"
				SubSystem="2"
				TargetMachine="17"
			/>
			<Tool Name="VCALinkTool" />
			<Tool Name="VCManifestTool" />
			<Tool Name="VCXDCMakeTool" />
			<Tool Name="VCBscMakeTool" />
			<Tool Name="VCFxCopTool" />
			<Tool Name="VCAppVerifierTool" />
			<Tool Name="VCWebDeploymentTool" />
			<Tool Name="VCPostBuildEventTool" />
		</Configuration>
		<Configuration
			Name="Release|Win32"
			OutputDirectory="..\VS2005\$(PlatformName)\$(ConfigurationName)"
			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)\$(ProjectName)"
			ConfigurationType="2"
			UseOfMFC="1"
			CharacterSet="2"
			DeleteExtensionsOnClean="*.obj;*.ilk;*.tlb;*.tli;*.tlh;*.tmp;*.rsp;*.pgc;*.pgd;$(TargetPath)"
			WholeProgramOptimization="1"
			>
			<Tool   Name="VCPreBuildEventTool" />
			<Tool   Name="VCCustomBuildTool" />
			<Tool   Name="VCXMLDataGeneratorTool" />
			<Tool   Name="VCWebServiceProxyGeneratorTool" />
			<Tool   Name="VCMIDLTool" />
			<Tool   Name="VCCLCompilerTool"
				AdditionalIncludeDirectories="..\core;"
				PreprocessorDefinitions="WIN32;NDEBUG;_WINDOWS;_USRDLL;_CRT_SECURE_NO_DEPRECATE;_NO_CPPUNIT"
				RuntimeLibrary="0"
				UsePrecompiledHeader="0"
				WarningLevel="3"
				Detect64BitPortabilityProblems="true"
				DebugInformationFormat="3"
				DisableSpecificWarnings="4996"
			/>
			<Tool   Name="VCManagedResourceCompilerTool" />
			<Tool   Name="VCResourceCompilerTool" />
			<Tool   Name="VCPreLinkEventTool" />
			<Tool   Name="VCLinkerTool"
				LinkIncremental="1"
				AdditionalLibraryDirectories="$(OutDir)"
				GenerateDebugInformation="true"
				SubSystem="2"
				OptimizeReferences="2"
				EnableCOMDATFolding="2"
				TargetMachine="1"
			/>
			<Tool   Name="VCALinkTool" />
			<Tool   Name="VCManifestTool" />
			<Tool   Name="VCXDCMakeTool" />
			<Tool   Name="VCBscMakeTool" />
 			<Tool   Name="VCFxCopTool" />
			<Tool   Name="VCAppVerifierTool" />
			<Tool   Name="VCWebDeploymentTool" />
			<Tool   Name="VCPostBuildEventTool" />
		</Configuration>
		<Configuration
			Name="Release|x64"
			OutputDirectory="..\VS2005\$(PlatformName)\$(ConfigurationName)"
			IntermediateDirectory="$(PlatformName)\$(ConfigurationName)\$(ProjectName)"
			ConfigurationType="2"
			UseOfMFC="1"
			CharacterSet="2"
			DeleteExtensionsOnClean="*.obj;*.ilk;*.tlb;*.tli;*.tlh;*.tmp;*.rsp;*.pgc;*.pgd;$(TargetPath)"
			WholeProgramOptimization="1"
			>
			<Tool   Name="VCPreBuildEventTool" />
			<Tool   Name="VCCustomBuildTool" />
			<Tool   Name="VCXMLDataGeneratorTool" />
			<Tool   Name="VCWebServiceProxyGeneratorTool" />
			<Tool   Name="VCMIDLTool"
				TargetEnvironment="3"
			/>
			<Tool   Name="VCCLCompilerTool"
				AdditionalIncludeDirectories="..\core;"
				PreprocessorDefinitions="WIN32;NDEBUG;_WINDOWS;_USRDLL;_CRT_SECURE_NO_DEPRECATE;_NO_CPPUNIT"
				RuntimeLibrary="0"
				UsePrecompiledHeader="0"
				WarningLevel="3"
				Detect64BitPortabilityProblems="true"
				DebugInformationFormat="3"
				DisableSpecificWarnings="4996"
			/>
			<Tool   Name="VCManagedResourceCompilerTool" />
			<Tool   Name="VCResourceCompilerTool" />
			<Tool   Name="VCPreLinkEventTool" />
			<Tool   Name="VCLinkerTool"
				LinkIncremental="1"
				AdditionalLibraryDirectories=""$(OutDir)";"$(SolutionDir)$(PlatformName)\$(ConfigurationName)""
				GenerateDebugInformation="true"
				SubSystem="2"
				OptimizeReferences="2"
				EnableCOMDATFolding="2"
				TargetMachine="17"
			/>
			<Tool   Name="VCALinkTool" />
			<Tool   Name="VCManifestTool" />
			<Tool   Name="VCXDCMakeTool"  />
			<Tool   Name="VCBscMakeTool" />
			<Tool   Name="VCFxCopTool" />
			<Tool  Name="VCAppVerifierTool" />
			<Tool  Name="VCWebDeploymentTool" />
			<Tool   Name="VCPostBuildEventTool" />
 		</Configuration>
	</Configurations>
	
	<Files>
		<Filter
			Name="Source Files"
			Filter="cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx"
			UniqueIdentifier="{<<<GUID>>>}"
			>
			<File RelativePath=".\<<<CLASS>>>.cpp" >
			</File>
			<File RelativePath=".\main.cpp" >
			</File>
		</Filter>
		<Filter
			Name="Header Files"
			Filter="h;hpp;hxx;hm;inl;inc;xsd"
			UniqueIdentifier="{<<<GUID>>>}"
			>
		</Filter>
		<Filter
			Name="Test files"
			>
		</Filter>
		<File
			RelativePath=".\Makefile.am"
 			>
		</File>
	</Files>
	<Globals>
	</Globals>
</VisualStudioProject>

Linux/Mac test

You should be able to build, install, and test the new module successfully

host% cd workdir
host% autoreconf -isf
... messages ...
host% ./configure
... messages ...
host% make
... messages ...
host% sudo make install
... messages ...
host% gridlabd --libinfo example
Module name....... example
Major version..... 3
Minor version..... 0
Classes...........
Implementations... 
Globals...........

If you have installed doxygen on your system, you may also test the source documentation

host% cd workdir
host% doxygen doxygen/gridlabd.conf
host% open ../documents/html/index.html

On some Linux systems you may have to name your browser instead of using open.

Your example module should be listed in the Files list and in it you should find main.cpp.

Windows test

Build the new module by pressing Shift-Ctrl-B. If you entered --libinfo $(TargetName) for the debugging command arguments (see above), then select the new project as the active project and run it by pressing Ctrl-F5. The following output should be displayed in the console

Module name....... example
Major version..... 3
Minor version..... 0
Classes...........
Implementations... 
Globals...........

If you have installed doxygen on your system, you may also build the doxygen-doc project (it is not automatically built). You can then open workdir/VS2005/docs/html/index.html to view the result.

Your example module should be listed in the Files list and in it you should find main.cpp.

See also

• Guide to Programming GridLAB-D
  • Introduction
    • Developer prerequisites
    • Programming conventions
    • Build/release process
    • Documentation Guide
    • Theory of operation
  • Creating a module
    • Module globals
    • Module functions
    • Subsecond processing
    • Import/export
    • Check
    • KML output
    • Example 1
  • Creating a class
    • Class functions
    • Class globals
    • Publishing properties
    • Publishing methods
    • Notifications
    • Load methods  New in 3.2! 
    • Example 2
  • Special Topics
    • Data types
    • Multithreading
    • Application links
    • Realtime server
    • Graphical user interfaces
    • Troubleshooting messages
    • Example 3
  • Source documentation
    • C/C++ Module API documentation (trunk)
    • C/C++ Module API Guide
    • Example 4
  • Validation
    • Example 5
  • Debugging
    • Debug option
    • VS2005 (MS Windows)
      • use_msvc
    • gdb option (linux/mac)
      • gdb_window
    • Runtime Class Debugging
      • compile_once
  • Code templates