Skip to contents

Installing and building Hector

Source: vignettes/articles/BuildHector.Rmd
BuildHector.Rmd

There are many ways to use Hector: as a stand-alone executable, through the online HectorUI, and as an R package. Here we provide installation and building instructions for the R Hector package and the executable.

R Hector

To install R, follow the official instructions for your platform.

Follow this YouTube video or continue reading.

To install the version associated with the current main git branch on GitHub, use the remotes::install_github` function. This will automatically install all of Hector’s dependencies as well. (Note that because this requires compiling from source, you will need to have a C compiler installed and configured.)

On Windows, you will also need to install Rtools. Download and instructions can be found here. After installation, there is another step to put the Rtools make utilities on the system PATH. This will allow you to compile R packages.

To do so, create a text file .Renviron in your Documents folder with the following line: PATH="${RTOOLS40_HOME}\usr\bin;${PATH}".

This can be done either with a text editor or in R itself:

writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")

Remember to restart R (or Rstudio) and to verify that make can be found. Executing Sys.which("make") should show the path to your Rtools installation.

On Mac OS and Linux, the required tools should be included as part of a standard R installation.

# If the `remotes` package isn't installed, first run:
# install.packages("remotes")
remotes::install_github("jgcri/hector")

Hector’s mandatory dependencies are listed in the DESCRIPTION file under Imports, and are currently as follows:

  • Rcpp – Facilitates integration of C++ code into R packages
  • BH – Boost C++ header files

Standalone Executable

Hector can also be compiled as a standalone executable. Unlike the R package, this method of installation does not automatically pull in dependencies, so you will have to install them manually.

Hector’s only external dependency, Boost, is a free, peer-reviewed portable C++ source library, available at http://www.boost.org/. Hector primarily uses Boost “header-only” libraries, which do not need to be compiled independently and only need to be extracted and included with the Hector source. Note that if your C++ compiler or standard library does not support the C++ 17 standard then the Boost system and filesystem libraries will need to be compiled/installed (see below).

Command Line (Linux & Mac OSX)

The Hector makefiles look for Boost libraries and headers in certain locations; these defaults can be overridden by setting the following environment variables:

  • BOOSTROOT (default /usr/local/). This variable should contain the full name of a directory with include/ and lib/ subdirectories that contain, respectively, the Boost header and library files. If you installed Boost using a package manager, this is likely where it is. If you built Boost from source or used a tool such as Homebrew to install Boost, then you will need to set this variable explicitly.

Alternatively, if the header and library locations are not subdirectories of a single directory, you can set BOOSTINC and BOOSTLIB variables to their respective locations. In this case, BOOSTROOT is ignored.

  • GTROOT (default /usr/local/). This variable should contain the full name of a directory with include/ and lib/ subdirectories that contain, respectively, the Googletest header and library files. Alternatively, if the header and library locations are not subdirectories of a single directory, you can set GTINC and GTLIB variables to their locations. In this case, GTROOT is ignored. Note that this is only needed if you want to run the Hector unit tests. It’s not needed for running the model.

Shared Library Search Path

If your C++ compiler or standard library does not support the C++ 17 standard (see below), then the Boost libraries used by Hector will be compiled into shared libraries that must be loaded at run time. It is best if these libraries are in directories that are part of your system’s shared library search path. On many systems /usr/local is already in that path.

If you are unable to add your library installation directory to the library search path, you will need to add the installation directory to the environment variable LD_LIBRARY_PATH. Try not to use this approach if you can help it, because it can cause some conflicts with other software on your system. Instead, ask your system administrator if ldconfig is right for you.

Build & Run Hector

Once the necessary libraries are installed, change to the top-level Hector directory and type make hector. The Hector executable will be built in the source/ subdirectory. If you ever need to rebuild, you can type make clean to clear away the executable and all of the intermediate files.

There are two additional environment variables that you can use to fine-tune the build process. The CXXEXTRA variable is passed to the C++ compiler. You can use this variable to pass extra options to the compiler without changing the Makefile. In particular, specifying optimization options in CXXEXTRA such as -O or -O0 will override the default value of -O3.

The CXXPROF variable is passed both to the compiler and the linker. It is intended to turn on performance profiling, which must be specified at both the compile and link stages of the build, so it generally should be either unset (for normal operation) or set to -pg (for profiling). Profiling slows the code down dramatically, so if you use it, be sure to unset CXXPROF, clean the build directories with make clean, and rebuild when you are ready to go back to production runs.

No std::filesystem Support

If your C++ compiler or standard library is too old, it will not support the C++ 17 std::filesystem. In this case you may receive errors while building Hector such as the following:

g++  -L.  -o hector main.o -lhector -lm 
./libhector.a(ini_to_core_reader.o): In function `boost::filesystem::exists(boost::filesystem::path const&)':
/pic/projects/GCAM/GCAM-libraries/include/boost/filesystem/operations.hpp:404: undefined reference to `boost::filesystem::detail::status(boost::filesystem::path const&, boost::system::error_code*)'

Or on versions of macOS prior to Catalina (10.15):

ini_to_core_reader.cpp:159:17: error: 'path' is unavailable: introduced in macOS
      10.15
            fs::path csvFilePath( csvFileName );
                ^

In this case, you can set an environment variable:

export NO_CXX17=1

and will need to Compile Boost Libraries – specifically, the system and filesystem libraries. Finally, ensure that the environment variable BOOSTROOT or BOOSTLIB is set properly (see above).

Running Hector

Run Hector from the terminal:

./src/hector ./inst/input/name-of-ini.ini

To build and run the Hector unit tests, type make testing and then

./src/unit-testing/hector-unit-tests

Xcode (Mac OS X)

These directions assume a basic familiarity with Xcode and Mac OS X software installation.

  • Install Xcode if necessary. Hector has been built and tested with MacOS >= 10.8.5, up to Monterey (12.6.1). The project files are for Xcode 14.1.
  • Download and install Boost, following the instructions above.
  • Download the Hector zip file or check out the repository using Git.
  • From Xcode, open the project file in project_files/Xcode/hector.xcodeproj.

The Xcode project file is configured to use constants defining custom paths, rather than hard-coded paths. This means that developers and users can set these paths without overwriting each other.

  • As a result, you will need to set several custom paths (Preferences -> Locations -> Custom Paths): BOOSTROOT, and HECTORDIR.
    • BOOSTROOT is the root directory where the Boost headers can be found in boost/.
    • HECTORDIR should be set to root directory for the model (the repository root) Xcode will use this path to the ini files used by the various schemes and write the csv files to the output directory.
  • If you want to build Hector’s testing framework (the hector-tests target; this is optional and only relevant for C++ developers) add GTEST and GTESTLIB custom paths to Xcode; these are analogous to their Boost counterparts. You will need to install googletest on your machine.

At this point you should be ready to go:

  • Build the project, making sure you’re building the hector target.
  • Run!
  • To run a different scenario, change the current Scheme settings (Scheme->Edit Scheme) and modify or add a command-line argument (Arguments tab, e.g. “./inst/input/hector_ssp245.ini”).

The Xcode profile file includes a hector-tests target that builds the unit testing framework described above.

Xcode Resources

Visual Studio / Microsoft Visual C++

  • Install Visual Studio and be sure to the Visual C++ add-on as well.
  • Download and install Boost.
  • Set the environment variables:
    • BOOSTROOT to the location to which you installed Boost (e.g. C:\boost_1_75_0)
  • Open the Visual Studio project file which is located in your Hector repository under project_files/VS/hector.sln
  • Build the hector target
  • To run Hector:
    • From the CMD prompt: project_files/VS/x64/Release/hector.exe ./inst/input/name-of-ini.ini
    • From with in the Visual Studio debugger (the working directory will default to project_files/VS): x64/Release/hector.exe ../../inst/input/name-of-ini.ini