Skip to content

Building EnergyPlus

Jump to bottom Edit New page
Julien Marrec edited this page Aug 18, 2023 · 2 revisions

Building EnergyPlus

Now the fun part, building EnergyPlus. The build process is setup by CMake. On all platforms, you will need to install git and an optional git GUI client, clone the repository to your machine, then create a folder for building. This build folder is commonly placed right next to the source folder, but doesn't have to be. The repository folder will be called the source tree, and the build folder is called the build tree. The steps for each platform are described in the following sections, followed by instructions for building installer packages, documentation, and Fortran utilities.

Windows

When installing git, watch for options about line endings and select "automatic" so that local files will use Windows CRLF line endings and they will be automatically converted to/from the unix-style line endings in the git repository.

The C++ code in EnergyPlus utilizes many modern C++ features, and so a modern compiler is required. On Windows, as of Spring 2019, the requirement is Visual Studio 2017 or later. Using GCC on Windows is fine, but instructions aren't provided here.

  1. Install Visual Studio Community. For best results use VS Community 2017 15.7.0 or later which includes ClangFormat support. This is available here. The installer presents several "Workloads" to choose from, select "Desktop development with C++".
  2. Install the latest Python 3 release.
  3. Install cmake from here. This includes a GUI. From the start menu, you should be able to launch the gui (it is called cmake-gui). You should use at least CMake 3.10+.
  4. Point cmake source code to the root of the repository, the root of the source tree. e.g. C:\GitHubClones\EnergyPlus
  5. Point cmake build to the folder you created, the root of the build tree. CMake will offer to create this folder if it doesn't exist. e.g. C:\GitHubClones\EnergyPlus\Build (This may be anywhere on your system, but this arrangement is convenient, because the EnergyPlus repo ignores folders named Build or build.)
  6. Click configure. This may bring up a dialog box where you choose the build environment to use. Choose Visual Studio 15 or Visual Studio 15 Win64 (for 64-bit builds), which is the 2017 version of the toolchain. If you are upgrading an existing build folder, delete the CMake cache first. If Visual Studio 15 does not show in the list, check to see if you have the latest version of CMake.
  7. Check the configuration settings, keeping them default should suffice, and click Generate.
  8. Browse to the build folder and there will be a Visual Studio solution file you can click on, EnergyPlus.sln. It will include multiple projects for each build target. The build type typically defaults to Debug, which will allow you to step through the execution of the program. Debug executables are typically slower than Release executables, so if you intend to run real simulations, you will probably want to do a Release build. Choose the type of build (Debug or Release), then right click on EnergyPlus in the solution explorer and "Build". This will build EnergyPlus and all of its dependencies. The target executables will be found in the Products subfolder.
  9. The solution will include the ZERO_CHECK project as the default target to run when you execute, so when you are ready to debug, manually set the default target to EnergyPlus.
  10. For the EnergyPlus project, right click on the project and select Properties. Under Configuration Properties select Debugging. In the Working Directory field, enter $(SolutionDir)\Products. This is the target path for the Energy+.idd file and will be the working directory for interactive debugging. Put in.idf, in.epw and the like here. Or enter command line arguments in the Command Arguments field to specify the locations of files.

Linux

These instructions were written around Ubuntu, but should be valid for other Debian/*buntu and Linux-in-general distributions. The differences will be in the package-management system commands, and possibly in the shell being used (sh, bash, zsh, etc.).

  1. Make sure the installed compilers are sufficient for compiling the code. The latest LTS version of Ubuntu is 18.04, and the g++ version available in the default repository is sufficiently updated for compiling EnergyPlus. On Debian/Ubuntu, apt-get install g++ will install the compiler.
  2. Nearly every distribution will include a Python3 interpreter already, but install one if not.
  3. Install CMake tools. For Debian/Ubuntu, apt-get install cmake cmake-curses-gui installs CMake and a terminal-based user interface.
  4. Navigate in the terminal to the root of the build tree (see above). You will launch CMake from this location. CMake also needs to know where the source code is located, the source tree. The program must be passed an argument that specifies the location of the root of the source tree. For example, if the build tree is directly next to the source tree and the source tree is named "EnergyPlus", the command could be called for the default build environment by executing the CMake GUI as: ccmake ../EnergyPlus
  5. Configure the build in ccmake by pressing c. By default, the build type is set to "Release", but this can be changed to "Debug" (or other build types) from within ccmake. If the Fortran utilities and/or installation packages are to be built, turn on the BUILD_FORTRAN and/or the BUILD_PACKAGE options at this step. If changes have been made to the source, consider building the unit tests by turning on BUILD_TESTING. Press c again to complete configuration, then g to generate Makefiles.
  6. Staying in the build tree, run make -j N, where N is the number of process to employ to build the project. To build installation packages, run make -j N package

At the completion of this process, the build tree will contain a subdirectory named "Products" that contains the built executables. If installation packages have been built, these will be in the root of the build tree.

Mac

These instructions were written for Mac OS X Version 10.15. Newer versions of OS X are expected to work, but not yet tested. Older versions of Mac OS X may work with some tweaking of the project configuration, but are not supported at this time.

  1. Install Xcode which is available on the App Store.
  2. Install the latest Python 3 release.
  3. Install CMake from http://www.cmake.org/download/.
  4. Launch CMake.app and click the "Browse Source" button, then select the directory where the source is located. (Alternatively, you may use ccmake from the command line similar to the Linux instructions.)
  5. Make a new directory at the root of the source tree called build.
  6. In CMake.app "Browse Build" and select the new build directory.
  7. Press Configure. By default, the build type is set to "Release", but this can be changed to "Debug" (or other build types) from within CMake.app.
  8. When prompted to specify the generator choose "Unix Makefiles" and default native compilers.
  9. Press Generate.
  10. Using the command line interface of Terminal.app navigate to the build directory.
  11. Type make -j N, where N is the number of processes you'd like to employ to build the project.

Building Installer Packages

Building an installer package is simply a matter of compiling the "Package" target.

On Windows and Mac, you must install the Qt Installer Framework (currently tested on v3.0.6, available here). After installing QtIFW, you must add the executable directory to your system path:

On Mac: e.g., adding export PATH="/Users/[username]/Qt/QtIFW-3.0.6/bin:$PATH" to your ~/.bash_profile or similar.

On Windows: Settings --> System --> About --> System Info --> Advanced System Settings --> Environment Variables, then edit the Path variable and add the path to QtIFW, e.g. C:\Qt\QtIFW-3.1.1\bin (a restart is required for the change to take effect).

Once the appropriate packaging tool is installed, use the CMake interface to turn on the BUILD_PACKAGE option, and for Mac, set CPACK_BINARY_IFW to ON (press t to toggle advanced options to display this option), and regenerate the project. Run make package or run the package build target in Visual Studio to generate the package. The completed installer package will be copied into the root of the build directory.

Building Documentation

EnergyPlus documentation source is written in LaTeX. To build the document PDFs you will need a working LaTeX compiler (specifically, xelatex) for your operating system:

  • Windows: MiKTeX

    Note: When installing, set "Install missing packages on-the-fly" to "Yes", not "Ask me first".

    Note: Set the Windows operating system path environment variable to point to the MiKTex binary files, e.g. C:\Program Files\MiKTeX 2.9\miktex\bin\x64

    If a memory error occurs, such as TeX capacity exceeded, sorry [main memory size=3000000], follow these instructions (adapted from here) to increase the memory allocation:

    Execute the following command in your prompt (Windows > Run > "cmd")

    initexmf --edit-config-file=xetex

    This opens an editor where you can put the new values. E.g.

    main_memory=5000000 
extra_mem_bot=5000000 
font_mem_size=5000000 
pool_size=5000000 
buf_size=5000000

    Save the file, then execute initexmf --dump=xetex to update the LaTeX format files.

  • Mac: MacTeX

  • Linux: TeX Live

Use the CMake interface to select the desired "DOCUMENTATION_BUILD" option: BuildWithAll will build the PDFs the next time you build/make the project. BuildOnlyWithPackage will build the PDFs whenever PACKAGE is built. Each document has it's own build command, and CMake will only re-compile documents where the source files have changed. The compiled PDFs are written to your build directory in a sub-directory called doc/pdf. If DoNotBuild is selected, the Documentation projects will not be present in the configuration.

Building Fortran

The ExpandObjects and Transition utilities are written in Fortran.

For Windows, install MinGW - Minimalist GNU for Windows mingw-get-setup.exe

  • Select Basic Setup and mark minggw32-base and mingw32-gcc-fortran for installation,
  • Under Installation select Apply Changes (5.3.0-3)
  • In CMake turn on "BUILD_FORTRAN" (CMake may report "Looking for a Fortran compiler - NOTFOUND". This is OK.)
  • The EnergyPlus.sln in Visual Studio should now include projects named ExpandObjects_build, Transition_build, and others which may be built separately and will build automatically when building a package.

For Linux, use apt-get install gfortran to get a Fortran compiler. For macOS, brew install gcc will also install gfortran, or you can download mac binaries by reading the gcc wiki page here. Once installed, follow the same pattern as Windows of enabling the BUILD_FORTRAN CMake flag. Once complete, you should have access to build the Fortran targets in the code.

Add a custom footer
Add a custom sidebar
Clone this wiki locally