Code Contributions

Prerequisite Software

If you’ve found an issue you’d like to fix, you’ll need to compile Vapor, fix the issue at hand, and submit your chang es for review and approval. Prerequisite software for all platforms includes:

• Git

• CMake (version 3.20 or higher)

One of the following compilers will be necessary:

Operating System	Compiler
MacOS	Custom OMP version of clang
Ubuntu/CentOS	g++ 7.5.0 or higher
Windows	Microsoft Visual Studio 2015, version 14

Finally, consult VAPOR’s CI build system for necessary system libraries on MacOS, Windows, and Linux.

Acquire Source Code

After installing Git and registering with GitHub, it’s time to “Fork” Vapor’s code base by clicking the Fork button on the upper right corner of Vapor’s GitHub repository. This creates your own repository on GitHub that contains a copy of Vapor’s current main branch.

Click the “Fork” button in the top-left corner of we website.

The newly created fork, based off Vapor’s main branch. Note the new repository name (sgpearse/VAPOR). This is the repository you will clone from.

Clone your forked repository to a suitable location on your local work machine. This new remote repository is what will be merged with Vapor’s main branch once your changes have been made.

After completing your work, your changes can be submitted for review through a Pull Request from your Fork into Vapor’s main repository. This is done under the Pull Requests tab in Vapor’s github repository. From this tab, create a new pull request that brings the changes from your forked repo into Vapor’s main repo. More details on this step are included in the Submitting Your Changes section of this document.

For more information on the Forking Workflow, please see Atlassian has a tutorial on basics and best practices.

Submitting a pull request to Vapor’s main branch.

Third-Party Libraries

Download third party libraries here

Windows:

Unzip the third-party libraries for Windows into the root of your C:\ directory.

Linux and MacOS:

The third party libraries must be placed in /usr/local/VAPOR-Deps/ along with a symbolic link named “current” that points to them.

$ ln -s /usr/local/VAPOR-Deps/2023-Jun /usr/local/VAPOR-Deps/current

MacOS:

A “quarantine” flag will be added to the binaries and libraries you build from source. This will prevent them from being run. To remove the flag, run:

$ sudo xattr -dr com.apple.quarantine /usr/local/VAPOR-Deps/current/* after building the libraries.

Building Third-Party Libraries

Download source files here.

See ~/VAPOR/scripts/build3rdParty.sh to compile the libraries and see specifics on how they are configured for maxOSx86, appleSilicon, and Ubuntu.

~/VAPOR/scripts/build3rdParty.sh -o macOSx86
~/VAPOR/scripts/build3rdParty.sh -o appleSilicon
~/VAPOR/scripts/build3rdParty.sh -o Ubuntu

Build instructions for Windows can be found here.

Note

The file <vapor-source>/site_files/site.NCAR may be used to specifiy the location of the libraries. To do this, build your version of the libraries in /usr/local/VAPOR-Deps/current, or change the THIRD_PARTY_LIB_DIR path in site.NCAR.

Vapor	3.9.3
assimp	5.2.5
expat	2.5.0
freetype	2.13.0
glew	N/A
glm	0.9.9.8
hdf5	1.12.2
hdf5 plugins	1.12.2
jpeg	9e
libgeotiff	1.7.1
netCDF	4.9.1
Ospray	2.11.0
proj	7.2.1
python	3.9.16
Qt	5.15.8
tiff	4.5.0
udunits	2.2.28
xcb-proto	1.15.2
libxcb	1.15.0

Install System Libraries

Building Vapor from source requires system libraries that are not natively available on all UNIX platforms. The following commands can be used to acquire these libraries.

Ubuntu:

sudo apt-get install git freeglut3-dev libexpat1-dev libglib2.0-0 libdbus1-3

CMake and make

To build from source, create a directory where the build will take place. For example:

> cd ~/VAPOR > mkdir build > cd build

Windows

Enter your build directory as the “Where to build the binaries” field in the CMake GUI. Click Configure, Generate, and then Open Project in that order. Visual Studio will open, and you can build the target PACKAGE to compile the source code.

UNIX:

From your build directory, configure the software with cmake like so. Additional arguments can be added with -D<additional-argument>.

cmake ..

Now compile with make

make

Note

Some libraries have been optimized with the optional OpenMP API. If you wish to compile with these optimizations, you’ll need a compiler that supports OpenMP, as well as a few compiler flags which are documented here.

If compilation is successful, you can find Vapor’s executable in the bin directory within your build directory.

Changing CMake Variables

Some users may want their build to target a different library than what is distributed with Vapor’s 3rd party library bundle. Different libraries can be targetted in two ways, 1) through the ccmake tool, and 2) by editing the file located in <source-directory>/site_files/site.NCAR.

ccmake

Cmake provides an interface to set build variables called ccmake. From your build directory, you can issue the ccmake command, followed by the path to Vapor’s source code. If your build directory is in <source_directory>/build, issuing ccmake from this directory would look like this:

ccmake ..

ccmake’s interface for changing build variables after issuing “ccmake ..” on Vapor’s source directory. This is assuming your build directory is in <vapor_source>/build.

The above interface allows you to set targets for some (but not all) of Vapor’s libraries. More information on ccmake can be found here. Your changes will be saved in your build directory in a file named CMakeLists.txt. If this file gets deleted, your changes will be lost. To set your libraries in a more permanent fashion, you can edit the site.NCAR file, described below.

A configuration to generate a release installer may look like this:

camke -DBUILD_TYPE=Release -DDIST_INSTALLER=ON .. && make

Submitting Changes

After successfully compiling Vapor, you can make changes to the code base. Make sure to follow Vapor’s Code Conventions. If building on a UNIX system, eliminate all compiler warnings.

Build and Test an Installer

Before submitting your changes for review, it’s worth the time to build an installer to see if libraries are properly linked, and optimized code works correctly.

To build an installer, run ccmake <vapor-source-dir> so that the field CMAKE_BUILD_TYPE Debug is changed to CMAKE_BUILD_TYPE Release. Also change the field DIST_INSTALLER OFF to be DIST_INSTALLER ON. Alternatively to ccmake, you can hand-edit the file CMakeLists.txt, which is located in the root of Vapor’s source directory.

On Windows, make sure that the Visual Studio setting for the build is in Release mode, not Debug, and build the target PACKAGE.

On OSX, run cmake <vapor-source-dir> && make && make installer from your build directory.

On Linux, run cmake <vapor-source-dir> && make linuxpreinstall && make installer from your build directory.

Pull Request

After your implementation is complete, push your commits to your forked repository on GitHub. Then issue a pull request to Vapor’s main branch.

Manual Review:

If these tests pass, Vapor’s team will review the Pull Request to make sure that Vapor’s Code Conventions were honored, and that the logic and structure of the code is sound.

After review, further changes may be requested. If everything looks good, the Pull Request will be merged into Vapor’s main repository.

Vapor Coding Conventions

Codesigning MacOS

To codesign a MacOS .dmg installer, follow these steps:

1. Acquire VAPOR’s Developer ID Application certificate from our administrators and register it on your keychain

2. Generate a personal app-specific password and register it on your keychain*

3. Install your .dmg in the /Applications directory

4. Run the bash script buildutils/codesignMacOS.sh

Note

Read more about app-specific passwords here: https://support.apple.com/en-us/102654

A codesigned .dmg installer will now have been generated in the /Applications directory. If the code signature reports back from the Apple notarytool as invalid, it can be debugged by applying the submission’s hash as follows:

xcrun notarytool log --keychain-profile "<my app-specific password name>" <hash>

Building Vapor’s Python API from source

For generating a tar.bz2 installer bundle for testing or hosting on a remote server such as the one we use on Anaconda.org, you will need to install Anaconda or something similar. Once installed, fork Vapor’s github repository, then build and install the generated tar.bz2 bundle by following the steps below.

Building a local conda bundle

1. After forking Vapor and installing Anaconda, open a new console that will be in the (base) environment. Add access to the conda-forge channel, create a new environment with the packages conda-build and activate it.

conda config --add channels conda-forge
conda create -n myEnvironment conda-build
conda activate myEnvironment

2. After making necessary changes to the source code, cd into VAPOR’s /conda directory.

cd ~/VAPOR/conda

3. Execute the conda build command with default parameters or optional ones.

conda build . (default)
DEBUG_BUILD=false MAP_IMAGES_PATH="<path_to_images>" conda build . (extra options)

Note

If you get a build error referencing CMakeLists.txt at this point, delete everything in your VAPOR/build directory and try re-running the above command.

If the build is successful a tar.xz bundle will be created in a directory shown below, where <OS> represents the operating system the bundle was built for. $CONDA_PREFIX is a variable in your current conda environment.

$CONDA_PREFIX/conda-bld/<OS>/vapor-3.6.0-ha5a8b8e_0.tar.bz2

Operating System	Directory
MacOS x86	osx-64
MacOS ARM	osx-arm64
Linux x86	linux-64

Installing a local conda image

Once you’ve built a tar.bz2 image or downloaded one from another source, you can install it as follows.

Note

If you downloaded your .tar.bz2 file from another source, you will need to create a new environment with access to the conda-forge channel, and the conda-build and python=3.9 packages.

conda config --add channels conda-forge
conda create -n myEnvironment python=3.9 conda-build
conda activate myEnvironment

1. Within your conda environment, create a directory that will contain your installation. Our team typically uses ~/channel. Also create a subdirectory according to your operating system, shown below.

mkdir -p ~/channel/osx-64 (MacOS x86)
mkdir -p ~/channel/osx-arm64 (MacOS ARM)
mkdir -p ~/channel/linux-64 (Linux x86)

2. Move your created .tar.bz2 package from its build or download directory into your channel.

mv $CONDA_PREFIX/conda-bld/<OS>/vapor-3.6.0-ha5a8b8e_0.tar.bz2 ~/channel/osx-64
or
mv ~/Downloads/vapor-3.6.0-ha5a8b8e_0.tar.bz2 ~/channel/osx-64

3. Index your new local channel, so conda knows about it.

conda index ~/channel

4. Install your .tar.bz2 package. You must use a full file path to your channel.

conda install -c file://Users/myUserName/channel vapor

The installation can be ferified with the following commands in your console:

python
import vapor

Note

Example python scripts and jupyter notebooks can be found in $CONDA_PREFIX/lib/python3.<version>/site-packages/vapor

Python Open Source Utilities

Vapor Python supports a number of utility functions, found under apps/pythonapi/vapor/utils. If you write a function for your workflows that you believe would be useful to other users, we encourage you to add the function to Vapor utils.