HOWTO build OpenMx from the source repository

Contents

• General Requirements for compiling OpenMx
• Unix installation
• OSX installation
• Windows installation
• Buildbot

General Requirements for compiling OpenMx

Note 1: The source code for OpenMx is on GitHub as https://github.com/OpenMx/OpenMx

Note 2: If you are not a developer, you almost certainly do not need to build OpenMx from source. Just use install.packages('OpenMx') or the getOpenMx.R script.

Compiling OpenMx requires that you have installed in R the other packages to which we link, or depend. It can be useful to also install suggested packages. As of February 2023, these were:

It pays to update these prior to building OpenMx to ensure you have the latest versions...

You can install most of the packages used by OpenMx with the following code:

pkglist <- c("Rcpp", "RcppEigen", "StanHeaders", "BH","rpf", "digest", "MASS" , "Matrix", "Rcpp", "RcppParallel", "lifecycle", "mvtnorm", "numDeriv", "roxygen2", "lme4", "devtools"); install.packages(pkgs = pkglist) 

Depends

install.packages("R") 

Linking to

install.packages("Rcpp"); install.packages("RcppEigen"); install.packages("StanHeaders") ; install.packages("BH"); install.packages("rpf") 

Imports

install.packages("digest"); install.packages("MASS"); install.packages("Matrix") 

Suggests

install.packages("mvtnorm") # for tests 

install.packages("numDeriv") # for tests 

install.packages("lme4") # for tests 

install.packages("roxygen2") # for documentation 

install.packages("Rmpi") # for HPC, can skip 

install.packages("snowfall") # for HPC, can skip 

Note that if you need Rmpi on MacOS, you would need to install Open MPI so that the R package Rmpi can be built. You can get openmpi from https://www.open-mpi.org - root permission will be needed for the installation but it should go smoothly.

Unix installation

OpenMx should compile under any Unix with the GNU compiler (See above for instructions on installing this if necessary). First you need to get the source.

GIT Source Archive

OpenMx source code is available on GitHub. Development takes place on the 'master' branch. Once change sets on the master branch are 100% passing on our nightly test suite, changes are merged to the 'stable' branch. Any other branches are for work-in-progress and we can offer no stability guarantees.

Building and Installing OpenMx from the downloaded source

git clone https://github.com/OpenMx/OpenMx.git
cd OpenMx/
make install

Options for the make process are as follows:

make build # build a binary release of the OpenMx library for export.
make install # create the OpenMx library and tries to install it as an R library.
make check # create the OpenMx library and runs the R library checker.
make html # create the Sphinx documentation in the docs/build/html directory.  You will need to have the Sphinx package installed.
make pdf # create a pdf file in the build directory of the OpenMx documentation.
make clean # clean out the build subdirectory.  Sometimes you may need to run "make clean" if you get error messages with the other make build.
make test # run all the models in the demo and models/passing subdirectories.  The number of errors found will be reported (should be 0).

Problems With make

1. Try make clean

2. Ensure your copy of the source is up-to-date (navigate to the trunk directory of your local copy and git update):

   cd ~/OpenMx/
   git fetch origin
   git reset --hard origin/master   # or origin/stable
   

3. Checkout the repository again.
4. Make sure you have all the R dependencies installed.

5. Last but not least, make sure that if you are building for multicore, the command R points to R64, not to plain 32-bit R. For example, if the command

   which R

   returns /usr/bin/R, and

   ls -l /usr/bin/R

   returns /usr/bin/R@ -> /Library/Frameworks/R.framework/Resources/bin/R it would be necessary to fix this with

   sudo unlink /usr/bin/R
   sudo ln -s /Library/Frameworks/R.framework/Resources/bin/R64 /usr/bin/R
   

   Otherwise, you may encounter cryptic messages such as

   Error in dyn.load(file, DLLpath = DLLpath, ...) : 
     unable to load shared object '/Library/Frameworks/R.framework/Versions/2.14/Resources/library/OpenMx/libs/i386/OpenMx.so':
     dlopen(/Library/Frameworks/R.framework/Versions/2.14/Resources/library/OpenMx/libs/i386/OpenMx.so, 6): Symbol not found: _GOMP_parallel_end
     Referenced from: /Library/Frameworks/R.framework/Versions/2.14/Resources/library/OpenMx/libs/i386/OpenMx.so
     Expected in: dynamic lookup
   

macOS (OS X) installation

Compiling OpenMx from source on modern macOS (both Apple Silicon/arm64 and Intel/x86_64) requires installing the official R compiler toolchain, obtaining the OpenMP runtime library, and configuring R.

1. Install Xcode Command Line Tools: Run this command in a terminal window to get standard C/C++ compiler libraries: xcode-select --install

2. Install CRAN-Approved GNU Fortran: Visit the CRAN macOS Tools page and download the Universal installer package (.pkg) matching your R version:

   • For R 4.4.x / 4.3.x: Download gfortran-12.2-universal.pkg
   • For R 4.5.x+: Download gfortran-14.2-universal.pkg

   Run the installer. It will automatically install gfortran under /opt/gfortran/bin/gfortran. R is pre-configured to look in this directory automatically, so no manual PATH changes are required.

3. Install OpenMP Runtime Support: Apple Clang supports OpenMP compilation but doesn't ship with the runtime library.
   
   1. Run clang --version in Terminal to check your Apple Clang version (e.g. Apple Clang 1600.x).
   2. Go to the CRAN macOS OpenMP page and download the matching LLVM runtime (e.g. LLVM 17.0.6 for Xcode 16.0-16.2/Clang 1600, or LLVM 19.1.5 for Xcode 16.3+/Clang 1700).

   3. Important: Do not use a web browser to download (browser quarantine flags will block the library at runtime). Instead, download and install via Terminal:

      curl -O https://mac.r-project.org/openmp/openmp-17.0.6-darwin20-Release.tar.gz
      sudo tar fvxz openmp-17.0.6-darwin20-Release.tar.gz -C /
      

      This installs libomp.dylib into /usr/local/lib/ and headers into /usr/local/include/.

4. Configure local ~/.R/Makevars: Create or edit the file ~/.R/Makevars in your home directory (do not edit the system-wide R Makeconf) and add the following lines:

   # R-specific OpenMP flags for macOS (Apple Clang)
   SHLIB_OPENMP_CFLAGS = -Xclang -fopenmp
   SHLIB_OPENMP_CXXFLAGS = -Xclang -fopenmp
   SHLIB_OPENMP_FCFLAGS = -fopenmp
   SHLIB_OPENMP_FFLAGS = -fopenmp
   
   # Paths linking to the official macOS R OpenMP runtime in /usr/local
   LDFLAGS += -L/usr/local/lib -lomp
   CPPFLAGS += -I/usr/local/include
   

5. Install R Dependencies: Open R and run the following command to install required packages:

   pkglist <- c("Rcpp", "RcppEigen", "StanHeaders", "BH", "rpf", "digest", "MASS", "Matrix", "RcppParallel", "lifecycle", "mvtnorm", "numDeriv", "roxygen2", "lme4", "devtools")
   install.packages(pkgs = pkglist)
   

6. Clone the OpenMx Repository: Download the OpenMx source code into a local directory: git clone https://github.com/OpenMx/OpenMx.git cd OpenMx
7. NPSOL Solver (Optional): If building with the proprietary NPSOL solver, find the correct version of libnpsol.a (one copy is appended at the bottom of this wiki page) and copy it to inst/npsol/osx/.

8. Build and Install: Run the compilation command from the top directory of the OpenMx repository:

   • To compile with NPSOL: make install
   • To compile without NPSOL (pure open-source/CRAN version): make cran-install

   Validate the installation by running: make test (this runs the test suite and takes some time to complete).

For subsequent updates and rebuilds, the procedure is simple:

cd OpenMx
git fetch origin
git reset --hard origin/master
make install # or make cran-install

Windows installation

First install R and the packages that OpenMx "depends", "suggests", and "links to" as recommended above. You will then have to install Rtools. We recommend that you also install cygwin, but it might not be technically required. Rtools is a set of compilers and command line tools that R distributes for use with package development in Windows environments. Download the latest version of Rtools from their website and run the installer. It is currently hosted on the CRAN website, under "Download R for Windows" and then "Rtools".

Before installing Rtools, decide if you want to install cygwin. We recommend installing cygwin for developers because cygwin is a Unix emulator that comes in handy for many tasks. In particular, developers must have some way of managing the Git version control system that OpenMx uses and is hosted on GitHub. Cygwin is an excellent way to manage Git, but many graphical user interfaces for Git on Windows also exist. If you decide to use cygwin, then install the either the 64-bit or the 32-bit version. Be sure to search through and add "git" to the installation when asked what packages to install. Cygwin generally takes a while to install. Once installed add cygwin to your PATH variable. See here for help on setting the path in Windows 2000/XP/Vista/8/10. Cygwin is usually something like "C:\cygwin\bin".

Once you have installed (or decided against installing) cygwin, download the latest version of Rtools from their website and run the installer. It is currently hosted on the CRAN website, under "Download R for Windows" and the "Rtools". You will be given the opportunity to edit the PATH variable in the Rtools installation. You can edit during installation or after; it is up to you, but Rtools must be on your system PATH environment variable. See here for help on setting the path in Windows 2000/XP/Vista/8/10. The default R directory is placed in C:\Program Files\R\R-3.X.X\bin. The default Rtools directory is C:\Rtools.

When you examine your PATH variable on a 64-bit Windows system, it should have something like this in it: "C:\rtools42\usr\bin;C:\R\R-4.2.1\bin\x64;C:\cygwin64\bin". If you're on a 32-bit system, it should be the following instead: "C:\rtools42\usr\bin;C:\R\R-4.2.1\bin\i386;C:\cygwin\bin".

Once the above are installed, you should be ready to do development work and build your own version of OpenMx. If you have Cygwin, then you can clone the git repository as instructed under the Unix section. If you have some other Git interface, use that. We recommend cloning the OpenMx repository into a folder that does not contain any spaces in its absolute path. When running "make install" use the Windows cmd prompt and run it as Administrator if you want to install OpenMx to the R system package directory. If you receive a permission denied error when running "make install", follow the instructions on the "I don't have permission" item of the R FAQ.

Then follow the instructions for the Unix installation.

Buildbot

Commits to the source repository are automatically tested by our Travis CI.