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&mdash;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 // 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
 * 1) define DLMAIN
 * 2) include "gridlabd.h"

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):

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 <<>> in the example for each of which you must generate your own GUID.

 >>}" RootNamespace="gridlabd" Keyword="Win32Proj" > 	        			   <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="&quot;$(OutDir)&quot;;&quot;$(SolutionDir)$(PlatformName)\$(ConfigurationName)&quot;" 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="&quot;$(OutDir)&quot;;&quot;$(SolutionDir)$(PlatformName)\$(ConfigurationName)&quot;" 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</tt>.

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

Windows test
Build the new module by pressing Shift-Ctrl-B. If you entered --libinfo $(TargetName) </tt> 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</tt> to view the result.

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