This chapter describes how to install, configure and uninstall EnergyPlusToFMU.
To export an EnergyPlus simulation as an FMU, EnergyPlusToFMU needs:
EnergyPlusToFMU has been tested on:
To install EnergyPlusToFMU, proceed as follows:
The installation directory should contain the following subdirectories:
EnergyPlusToFMU comes pre-configured to handle the most common system configurations. Usually, you can simply create an FMU, as described in Creating an FMU, and everything will work.
The remainder of this section provides tips for configuring EnergyPlusToFMU to match your particular system and needs. This may be needed in case problems arise. In addition, you may wish to reconfigure EnergyPlusToFMU, for example to optimize the FMU code, or to change the memory model under which it runs.
EnergyPlusToFMU requires a C compiler and linker (in order to build the FMU), and a C++ compiler and linker (in order to build supporting tools). Configuring EnergyPlusToFMU mainly consists of:
EnergyPlusToFMU controls both aspects of the configuration using batch files on Windows, and shell scripts on Linux and Macintosh. Batch files have the extension .bat, while shell scripts have the .sh extension. For convenience, this guide refers to all such files as batch files.
EnergyPlusToFMU includes the following batch files:
Batch (shell) file | Purpose |
---|---|
compile-c.bat | Compiles a C source code file into an object file. |
link-c-exe.bat | Links object files, generated by the C compiler, into an executable (i.e., a stand-alone application). |
link-c-lib.bat | Links object files, generated by the C compiler, into a shared or dynamic link library. |
compile-cpp.bat | Compiles a C++ source code file into an object file. |
link-cpp-exe.bat | Links object files, generated by the C++ compiler, into an executable (i.e. a stand-alone application). |
test-c-exe.bat | Automates a test of batch files compile-c.bat and link-c-exe.bat. |
The EnergyPlusToFMU installation includes default versions of these batch files. However, the contents of these batch files depends on:
As shown above, the installation directory contains a batch subdirectory for each of the supported platforms. Therefore to configure your system, you should first identify the appropriate subdirectory.
Note that Python detects your platform when it runs. Therefore if you are using an emulator or virtual machine (for example, Cygwin under Windows, or a Windows virtual machine on a Mac), you should look in the subdirectory corresponding to the emulated operating system.
Each system-specific batch subdirectory includes sample batch files. In addition to the default versions, some alternate versions also may be present. The alternate versions can be identified in two ways:
Note that the default batch file is an exact copy of one of the supplied alternate versions. For example, in the win subdirectory, the default batch file compile-c.bat is the same as compile-c-mvs10.txt (the version for Microsoft Visual Studio 10).
Once you have identified the appropriate batch file subdirectory, you can either:
In addition to the batch files that run the compiler and linker, EnergyPlusToFMU includes a batch file that tests some of the existing batch files. In particular, batch file test-c-exe.bat tests the compiler and linker batch files which build an executable from C source code. Once these batch files work, it should not be difficult to make the other compiler and linker batch files work.
The batch file test-c-exe.bat runs the appropriate compiler and linker batch files, and tests the resulting executable. It reports its progress, and so should give information as to where problems occur, if any.
To run the basic test, open a command-line window (see Notation). Next, change to the appropriate batch file directory, and run the test batch file.
A sample session at the Windows DOS prompt:
# Change to the batch file directory.
> cd epfmu_install_dir\Scripts\win
# Run the batch file.
> test-c-exe.bat
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
get-address-size.c
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
32
== The address size should appear above ==
===== Cleaning up =====
A sample session in a Linux command shell:
# Change to the batch file directory.
> cd epfmu_install_dir/Scripts/linux
# Run the batch file.
# Note the "./" before the batch file name.
> ./test-c-exe.sh
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
32
== The address size should appear above ==
===== Cleaning up =====
A sample session in a MacOS Terminal window:
# Change to the batch file directory.
> cd epfmu_install_dir/Scripts/darwin
# Run the batch file.
# Note the "./" before the batch file name.
> ./test-c-exe.sh
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
64
== The address size should appear above ==
===== Cleaning up =====
In the sessions shown above, the test batch file successfully ran to completion. If the test batch file fails at some point, then you will have to modify either the compiler or linker batch file, or possibly both. See Modifying the batch files.
The test batch file automates the individual steps described in Checking compile-c.bat and Checking link-c-exe.bat below. Therefore as you fine-tune your configuration, you may want to look to those sections for help.
This section describes how to check the current version of batch file compile-c.bat. A later section describes checking link-c-exe.bat. Once these batch files work, it should not be difficult to make the other compiler and linker batch files work.
The check is to build and then run one of the EnergyPlusToFMU supporting applications. If the application builds and runs correctly, it reports whether your compiler generates 32-bit or 64-bit executables.
To check the compiler batch file, open a command-line window (see Notation). Next, change to the appropriate batch file directory, and run the compiler batch file. The compiler should produce an object file in the same directory.
A sample session at the Windows DOS prompt:
# Change to the batch file directory.
> cd epfmu_install_dir\Scripts\win
# Run the batch file.
> compile-c.bat ..\..\SourceCode\utility\get-address-size.c
# Check the object file.
> dir *.obj
get-address-size.obj
A sample session in a Linux command shell:
# Change to the batch file directory.
> cd epfmu_install_dir/Scripts/linux
# Run the batch file.
# Note the "./" before the batch file name.
> ./compile-c.sh ../../SourceCode/utility/get-address-size.c
# Check the object file.
> ls *.o
get-address-size.o
A sample session in MacOS Terminal:
# Change to the batch file directory.
> cd epfmu_install_dir/Scripts/darwin
# Run the batch file.
# Note the "./" before the batch file name.
> ./compile-c.sh ../../SourceCode/utility/get-address-size.c
# Check the object file.
> ls *.o
get-address-size.o
In the sessions shown above, the compiler batch file successfully built the object file. Unfortunately, this is not always the case. Reasons for failure fall into a few broad categories:
Successfully compiling get-address-size.c does not completely test the compiler batch files. In particular:
Once you have successfully compiled the source code file get-address-size.c into an object file, the next step is to link the object file into an executable.
Working in the same subdirectory where you built the object file, run the linker batch file. In response, the linker should produce an executable, called test.exe, which you should be able to run.
A sample session at the Windows DOS prompt:
# Run the batch file.
> link-c-exe.bat test.exe get-address-size.obj
# Check the executable.
> dir *.exe
test.exe
# Run the executable (32-bit system).
> test.exe
32
A sample session for both a Linux command shell and MacOS Terminal:
# Run the batch file.
# Note the "./" before the batch file name.
> ./link-c-exe.sh test.exe get-address-size.o
# Check the executable.
> ls *.exe
test.exe
# Run the executable (32-bit system).
> ./test.exe
32
Again, the batch file may not work, for a few reasons:
Successfully building test.exe does not completely test the linker batch files. In particular:
In all cases, comparing the batch files provided by the EnergyPlusToFMU installation may help solve some of these problems.
This section gives general advice for editing your batch files, in case the default versions do not work on your system, or in case you want to modify or replace the default versions (for example, to change the optimization level, or to use a different compiler/linker).
Unfortunately, it is beyond the scope of this document to give full instructions on installing and using developer tools such as compilers and linkers.
The EnergyPlusToFMU tools only use the batch files named in the table shown in subsection Batch files. Thus, editing compile-c-gcc.txt will have no effect on how the FMU gets created. Only compile-c.bat affects how EnergyPlusToFMU compiles C source code files.
If a batch file does not work, it may simply be a matter of changing the directory path hard-coded in the batch file. For example, the batch files for Microsoft Visual Studio list several known locations for finding the Visual Studio program files. If your machine has Visual Studio installed in some other location (say, on the “D:\” drive rather than on “C:\”), then editing the batch file to point to the correct path may be all that is needed.
On most systems, the compiler also can act as the linker (or call the linker, filling in appropriate options). Therefore once you have your system’s compiler working, try listing the same tool in the linker batch files.
If your compiler/linker environment comes with an integrated development environment (IDE), you often can use the IDE to determine appropriate flags for controlling the compiler and linker. For example, Microsoft Visual Studio is the standard IDE for Microsoft’s C/C++ compilers, and the configuration panels in Visual Studio show the flags corresponding to each option. Therefore if you are having problems compiling a source code file with a provided batch file, try using the IDE to compile that source code file, and check what options the IDE uses.
The following tips for finding the compiler/linker apply to Unix-like environments, including Linux and MacOS.
Unix-like environments often define cc as a link to the standard C compiler, and c++ as a link to the standard C++ compiler.
If you have a standard compiler on your search path, the which command will locate it. For example, entering the command:
> which gcc
will return the path to the gcc compiler, provided your system has it, and provided it is on the search path. Otherwise, which gcc will return nothing.
If you believe you have a certain compiler, but cannot find it on your search path, try the find command. For example, to locate the icc compiler, try:
> find /usr -name icc
> find /bin -name icc
> find /opt -name icc
> find / -name icc
The first three commands search specific directories that commonly contain developer tools (your system may not have all of these directories). The last command searches the entire directory tree (and may take quite a while).
The find command accepts wildcards. Put them in quote marks, in order to prevent the shell from operating on the wildcard. For example:
> find /usr -name "*icc*"
searches the /usr directory for any file whose name contains the string icc.
Finally, the apropos command may help:
> apropos compiler
will search your help files for information pertaining to compilers. Unfortunately, it may return many entries unrelated to compiling C and C++ source code.
Permissions problems arise on Unix-like systems. The batch files must have “execute” permission, meaning you are allowed to run the file as a set of commands. To check the permissions:
# Linux, MacOS:
> ls -lt *.sh
-rwxr--r-- ... link-c-lib.sh
-rwxr--r-- ... link-c-exe.sh
-rwxr--r-- ... compile-c.sh
-rwxr--r-- ... link-cpp-exe.sh
-rwxr--r-- ... compile-cpp.sh
All five of the default batch files should have “-rwx” at the beginning of the permissions block (indicating you are allowed to read, write, and execute the file). If not, then set the permissions:
# Linux, MacOS:
> chmod u=rwx,g=r,o=r *.sh
and try running the compiler batch file again.
The batch file that runs the C compiler, compile-c.bat, needs to indicate whether or not your C compiler/linker environment provides a non-standard function called memmove. While memmove is non-standard in C, it is standard for C++. Therefore many C environments provide it as well.
If your C compiler/linker environment does provide memmove, then the batch file should pass the macro definition HAVE_MEMMOVE to the compiler. The included batch files show how to define a macro for various compilers.
If, on the other hand, your C compiler/linker environment does not provide memmove, then do not define the macro in the compiler batch file.
If you are not sure whether or not your system provides the function, simply watch for any errors while building your first FMU. If you fail to define HAVE_MEMMOVE when your system has it, the linker will complain about duplicate definitions of memmove. Conversely, if you define HAVE_MEMMOVE when your system does not have it, the linker will complain about not being able to find memmove.
Some linkers need explicit instructions to link to library code. Libraries are needed to provide standard functions, such as printf, that are called by the EnergyPlusToFMU source code. If the linker emits an error message indicating it cannot find a particular function, then consult your development environment’s documentation to determine which libraries it may need.
Note that specifying libraries is often somewhat arcane. For example, on Unix-like systems, to link a library libm.a typically requires the linker flag -lm. Furthermore, the order in which libraries are linked can matter, and you may need to add another flag to indicate the path(s) where the linker should search for libraries.
To uninstall EnergyPlusToFMU, delete the installation directory.