.. highlight:: rest .. _installation: Installation and configuration ============================== This chapter describes how to install, configure and uninstall the EnergyPlusToFMU tools. Software requirements ^^^^^^^^^^^^^^^^^^^^^ To export an EnergyPlus simulation as an FMU, EnergyPlusToFMU needs: 1. Python 2.6 or 2.7. 2. A C compiler and linker. 3. A C++ compiler and linker. EnergyPlusToFMU has been tested on: - Linux Ubuntu 12.04. - Windows XP Professional. - Mac OS X 10.5 and 10.6. .. _installation directory: Installation ^^^^^^^^^^^^ To install the EnergyPlusToFMU package: 1. Download the installation file from the :doc:`download` page. 2. Unzip the installation file into any folder (hereafter referred to as the "installation directory"). Minimally, the installation directory should contain the following subdirectories: - ``Scripts`` - ``EnergyPlusToFMU`` (Python scripts that create an FMU from an IDF file) - ``batch-dos`` (batch files specific to Windows) - ``batch-linux`` (shell scripts specific to Linux) - ``batch-darwin`` (shell scripts specific to Mac OS X) - ``SourceCode`` (C and C++ source code for creating an EnergyPlus FMU) - ``EnergyPlus`` - ``Expat`` - ``fmu-export-prep-src`` - ``read-ep-file-src`` - ``utility-src`` Configuration ^^^^^^^^^^^^^ EnergyPlusToFMU requires a C compiler and linker (in order to build the FMU), and a C++ compiler and linker (in order to build some supporting tools). To run the compiler and linker, EnergyPlusToFMU uses the following batch files: +----------------------+-------------------------------------------------------+ | Batch 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). | +----------------------+-------------------------------------------------------+ The EnergyPlusToFMU installation includes default versions of these batch files. However, the exact contents of these batch files depends on: 1. The operating system. 2. The compiler/linker environment (e.g., gcc or Microsoft Visual Studio). 3. The options desired (e.g., a 32-bit or 64-bit FMU). Therefore configuring your installation may require modifying these files, according to your particular needs. First, identify the appropriate subdirectory where these batch files reside. As shown above, the `installation directory`_ contains a batch subdirectory for each of the supported platforms. 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: (1) the file extension is "``.txt``", rather than "``.bat``"; and (2) the file name identifies the associated options. For example, a file ``compile-c-gcc-32bit.txt`` is one possible version of ``compile-c.bat``. It is specific to the gcc compiler/linker environment, and it generates 32-bit object files even on a 64-bit machine. Note that the default batch file is an exact copy of one of the supplied alternate versions. For example, in the ``batch-dos`` subdirectory, the default batch file ``compile-c.bat`` is the same as ``compile-c-mvs10.txt`` (the version for Microsoft Visual Studio 10). Therefore the installation has fewer unique batch files than it at first appears. Checking compile-c.bat ^^^^^^^^^^^^^^^^^^^^^^ The included batch files cover some common cases. With luck, you can simply run the EnergyPlusToFMU build process described in :doc:`build`, and everything will work as expected. 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, then it should not be difficult to make the other compiler and linker batch files work. The check is to build one of the EnergyPlusToFMU supporting applications, and to make sure it runs. If successful, the application determines whether your compiler generates 32-bit or 64-bit executables. To check the compiler batch file, open a command window (e.g., a DOS prompt on Windows, a command shell on Linux, or a Terminal window on MacOS). The instructions that follow represent the command window like this: .. code-block:: none # This is a comment. > (This is the command prompt, where you enter a command) (If shown, this is sample output in response to the command) Note that your system may use a different symbol than "``>``" as the command prompt (for example, "``$``"). Furthermore, the prompt may include information such as the name of your system, or the name of the current subdirectory. To begin, change to the appropriate batch file directory. For example: .. code-block:: none # Windows: > cd epfmu_install_dir\Scripts\EnergyPlusToFMU\batch-dos # Linux: > cd epfmu_install_dir/Scripts/EnergyPlusToFMU/batch-linux # MacOS: > cd epfmu_install_dir/Scripts/EnergyPlusToFMU/batch-darwin Next, run the compiler batch file: .. code-block:: none # Windows: > compile-c.bat ..\..\..\SourceCode\utility-src\get-address-size.c # Linux, MacOS: # Note the "./" before the name of the batch file. > ./compile-c.bat ../../../SourceCode/utility-src/get-address-size.c In response, the compiler should produce an object file in the current directory. The object file should be called ``get-address-size.obj`` on Windows, and ``get-address-size.o`` on Unix-like systems. .. code-block:: none # Windows: > dir *.obj get-address-size.obj # Linux, MacOS: > ls *.o get-address-size.o Unfortunately, the compiler batch file can fail. Reasons for failure fall into a few broad categories: - You do not have permission to run the batch file. When you run the batch file, watch for output like "Permission denied" from the operating system. See `Troubleshooting permissions`_ below. - The source code file is not on the specified path. When you run the batch file, watch for output like "No such file or directory", along with the name of the source code file. Check the `installation directory`_ structure, as specified above. - The commands in the batch file are wrong for your system. This is the most likely cause of failure. The subsections below give hints on providing an appropriate ``compile-c.bat`` batch file. - The compiler did not accept some statement in source code file ``get-address-size.c``. In this case, please contact the EnergyPlusToFMU team to report the problem. Successfully compiling ``get-address-size.c`` does not completely test the compiler batch files. In particular: - Batch file ``compile-c.bat`` must specify whether or not your compiler/linker environment provides a function called ``memmove``. The simple application being tested here does not use ``memmove``, so this aspect of the compiler batch file is not checked. See `Troubleshooting the memmove function`_ below. - Batch file ``compile-cpp.bat`` must be configured for the C++ language, rather than the C language. Often no particular changes are required compared to ``compile-c.bat`` See the sample batch files in the standard distribution. Checking link-c-exe.bat ^^^^^^^^^^^^^^^^^^^^^^^ Once you have successfully compiled source code file ``get-address-size.c`` into an object file, the next step is to link the object file into an executable (i.e., a runnable program). Working in the same subdirectory where you built the object file, run the linker batch file: .. code-block:: none # Windows: > link-c-exe.bat test.exe get-address-size.obj # Linux, MacOS: # Note the "./" before the name of the batch file. > ./link-c-exe.bat test.exe get-address-size.o In response, the linker should produce an executable called ``test.exe``, in the current directory, and you should be able to run the executable: .. code-block:: none # Windows (32-bit example): > dir *.exe test.exe > test.exe 32 # Linux, MacOS (64-bit example): > ls *.exe test.exe > ./test.exe 64 Again, the batch file may not work, for a few broad reasons: - You do not have permission to run the batch file. When you run the batch file, watch for output like "Permission denied" from the operating system. See `Troubleshooting permissions`_ below. - The commands in the batch file are wrong for your system. The subsections below give hints on providing an appropriate ``link-c-exe.bat`` batch file. In particular, if the linker complains of not being able to find the standard library function ``printf``, see `Troubleshooting missing libraries`_ below. Successfully building ``test.exe`` does not completely test the linker batch files. In particular: - Batch file ``link-c-lib.bat`` has an additional complication. This batch file must link objects into a shared library. This generally will require passing a special switch or flag to the linker. - Batch file ``link-cpp-exe.bat`` must link objects generated by the C++ compiler. This may require providing different switches or flags to the linker, than used in ``link-c-exe.bat``. - Building ``test.exe`` uses a single object file. The linker batch file must be able to handle a list of object files. The provided batch files all do this correctly. Since proper behavior depends on the operating system, rather than on the linker, no problems should arise here. In all cases, comparing the batch files provided by the ``EnergyPlusToFMU`` installation may help solve some of these problems. Modifying the batch files ^^^^^^^^^^^^^^^^^^^^^^^^^ This section gives general hints on 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 altogether). 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 `configuration`_ table above. Thus, editing ``compile-c-gcc.txt`` will have no effect on how the FMU gets made. Only ``compile-c.bat`` affects the EnergyPlusToFMU tools. If a provided 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 as 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. Finding a compiler/linker on Unix ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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: .. code-block:: none > which gcc will return the path to the ``gcc`` compiler, provided your system has it, and provided it is on the search path. If you do not have gcc, or if you have gcc but it is not on the search path, then ``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: .. code-block:: none > 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: .. code-block:: none > find /usr -name "*icc*" searches the ``/usr`` directory for any file whose name contains the string "icc". Finally, the ``apropos`` command may help: .. code-block:: none > 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. Troubleshooting permissions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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: .. code-block:: none # Linux, MacOS: > ls -lt *.bat -rwxr--r-- ... link-c-lib.bat -rwxr--r-- ... link-c-exe.bat -rwxr--r-- ... compile-c.bat -rwxr--r-- ... link-cpp-exe.bat -rwxr--r-- ... compile-cpp.bat 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/run the file). If not, then set the permissions: .. code-block:: none # Linux, MacOS: > chmod u=rwx,g=r,o=r *.bat and try running the compiler batch file again. Troubleshooting the memmove function ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. However, yours may not. If your C compiler/linker environment does provide ``memmove``, then the batch file should pass the compiler the macro definition ``HAVE_MEMMOVE``. 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``. If, on the other hand, you define ``HAVE_MEMMOVE`` when your system does not have it, the linker will complain about not being able to find ``memmove``. Troubleshooting missing libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The linker batch files may have to use special flags to indicate which libraries to link against. In general, if you need to link against a library, it will be to provide a standard function, such as ``printf``, that is called by the EnergyPlusToFMU source code. If a linker batch file fails, and 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. Uninstallation ^^^^^^^^^^^^^^ To uninstall EnergyPlusToFMU, simply delete the `installation directory`_ where it was unzipped.