Skip to content

BUILDING.md

Latest commit

 

History

History
279 lines (214 loc) · 9.52 KB

BUILDING.md

File metadata and controls

279 lines (214 loc) · 9.52 KB

Build instructions

Documentation

Documentation are automatically created and published at readthedocs. However, if you would like to build the documentation locally, this can easily be done using scripts for Linux or macOS. Make sure to run these from the root of the repository.

Once the docs are built, you can access them in the directory _readthedocs/html.

To build a PDF of the FSD, run:

cd _readthedocs/html/fsd
pandoc --pdf-engine=xelatex \
  index.html FSD-BAGStructure.html FSD-Encapsulation.html \
  FSD-AxiomaticDefs.html FSD-BAGARB.html FSD-RevisionControl.html \
  FSD-Extensions.html FSD-Glossary.html FSD-References.html \
  FSD-Appendices.html RevisionHistory.html -o BAG_FSD_2.0.3.pdf

Docker

You can build a development Linux container using Dockerfile.dev by running the following command from the repository root directory:

docker buildx build -t dev/debian/baglib:latest -f Dockerfile.dev .

To build for a specific architecture, such as AMD64, run:

docker buildx build --platform=linux/amd64 \
  -t dev/debian/amd64/baglib:latest -f Dockerfile.dev .

To manually build and test inside the development container, run:

docker run -ti -v ./:/tmp/bag:rw dev/debian/baglib:latest /bin/bash
./scripts/dev-cont-build-bag.sh

After running dev-cont-build-bag.sh once, you can iteratively run Python tests by running:

python3 -m pytest python/test_*.py

Linux / macOS

Configure and build BAG

Build C++ library, tests, and example binaries:

$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -B build -S . \
 -DBAG_BUILD_TESTS:BOOL=ON -DBAG_CODE_COVERAGE:BOOL=ON \
 -DBAG_BUILD_PYTHON:BOOL=OFF -DBAG_BUILD_EXAMPLES:BOOL=ON
$ cmake --build build -j 8
$ BAG_SAMPLES_PATH=/ABSOLUTE/PATH/TO/REPO/BAG/examples/sample-data ninja -C build build ccov-all-export-lcov

Where /ABSOLUTE/PATH/TO/REPO/BAG/examples/sample-data should be replaced by the absolute path to the examples/sample-data directory within the BAG repo.

This will generate an HTML coverage report in build/ccov/all-merged/index.html.

Note: This will build with code coverage report generation for bag_tests when compiled with LLVM or GCC.

Note: On Linux/macOS, make sure to set CC=clang and CXX=clang++ to compile with clang and use llvm-cov. GCC and lcov will work, but the coverage exclusion configuration in the BAG project CMake configuration only works properly with LLVM, meaning that lcov coverage will include things like the C++ standard library, which will lead to inaccurate coverage percentages for the BAG tests.

Note: if you want to build documentation, add -DBAG_BUILD_DOCS:BOOL=ON to the CMake config. See the Read the Docs conda environment for dependencies needed to build documentation.

Build Python wheel

After building the C++ library in the build directory as above, you will be able to build a Python wheel for installing bagPy as follows:

$ python -m pip wheel -w ./wheel/ ./build/api/swig/python

Then you can install the wheel with:

$ python -m pip install ./wheel/bagPy-*.whl

Build examples only

Build examples only as follows:

$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B bag-examples -S . \
 -DBAG_BUILD_BAG_LIB:BOOL=OFF -DBAG_BUILD_EXAMPLES:BOOL=ON
$ cmake --build bag-examples -j 8

Note: This assumes you have either built baglib yourself, or installed binaries via conda.

Then run, for example bag_georefmetadata_layer:

$ ./bag-examples/examples/bag_georefmetadata_layer \
  examples/sample-data/bag_georefmetadata_layer.xml bag_georefmetadata.bag

Windows: Visual Studio 2022/2019

Locally build dependencies

Run docs\win-build\baglibs\downloads\download.ps1 to download dependencies.

Then to build dependencies run docs\win-build\baglibs\install\install.ps1.

Download swigwin-4.3.0 and upzip to docs\win-build\baglibs\install so that you have a directory named swigwin-4.3.0.

Note: You must run install.ps1 from an admin shell since libxml2 creates symlinks and Windows doesn't allow this from normal user shells.

Now, the build BAG, run the PowerShell script win-build.ps1. This will also run the C++ and Python tests.

Dependencies from Miniconda

Install miniconda & BAG dependencies

Download the latest version of miniconda from here and install to \miniconda (i.e., C:\miniconda).

Next, to install configure miniconda open a Developer Command Prompt in Visual Studio:

set PATH=\miniconda;\miniconda\Scripts;\miniconda\Library\bin;%PATH%
conda init # Restart your shell
conda update conda
conda config --add channels conda-forge
conda create -n bag-dev-env python=3.9
conda activate bag-dev-env
conda install cmake ninja hdf5 libxml2 swig catch2

Note: if using a different version of Python, modify conda create -q -n bag-dev-environment python=3.9 as needed.

Configure and build BAG

set CC=cl.exe
set CXX=cl.exe
cmake -Bbuild -S. -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=\miniconda\envs\bag-dev-env\Library -DBAG_BUILD_PYTHON:BOOL=ON -DBAG_BUILD_TESTS:BOOL=ON
cmake --build build
set PATH=build\api;%PATH%
set BAG_SAMPLES_PATH=examples\sample-data
build\tests\bag_tests.exe
python python\test_all.py

Dependencies from source

Note: We recommend using Dependencies from Miniconda as per above.

Setup output directory for build artifacts

mkdir \BAG

zlib

cmake -B build -G "Visual Studio 16 2019" -S . -DCMAKE_INSTALL_PREFIX:PATH=\BAG -DCMAKE_BUILD_TYPE=Release
cmake --build build --target install

Note: Use -G "Visual Studio 17 2022" for Visual Studio 2022.

libxml2

cmake -B libxml2-2.9.14-build -G "Visual Studio 16 2019" -S . -DCMAKE_INSTALL_PREFIX:PATH=\BAG -DCMAKE_BUILD_TYPE:STRING=Release -DLIBXML2_WITH_ZLIB=ON -DLIBXML2_WITH_ICONV=OFF -DLIBXML2_WITH_LZMA=OFF -DLIBXML2_WITH_PYTHON=OFF
cmake --build libxml2-2.9.14-build --config Release
cmake --install libxml2-2.9.14-build --config Release

Note: Use -G "Visual Studio 17 2022" for Visual Studio 2022.

HDF5

cmake -B build -G "Visual Studio 16 2019" -S . ^
 -DCMAKE_INSTALL_PREFIX:PATH=\BAG -DCMAKE_BUILD_TYPE:STRING=Release ^
 -DHDF5_BUILD_CPP_LIB=ON -DHDF5_BUILD_TOOLS:BOOL=OFF ^
 -DBUILD_TESTING:BOOL=OFF -DBUILD_SHARED_LIBS:BOOL=ON ^
 -DHDF5_BUILD_HL_LIB:BOOL=ON -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=ON ^
 -DZLIB_INCLUDE_DIRS=\BAG\include -DZLIB_LIBRARY:PATH=\BAG\lib\zlibd.lib
cmake --build build --config Release
cmake --install build --config Release

Note: BUILD_SHARED_LIBS must be set to ON.

Note: Use -G "Visual Studio 17 2022" for Visual Studio 2022.

Catch2

cmake -B build -G "Visual Studio 16 2019" -S . ^
 -DCMAKE_INSTALL_PREFIX:PATH=\BAG -DBUILD_TESTING:BOOL=OFF
cmake --build build --target install

Note: Use -G "Visual Studio 17 2022" for Visual Studio 2022.

SWIG (optional; required for Python support)

copy swig.exe \BAG\bin
xcopy /s Lib \BAG\lib

Configure and build BAG project for developing

Without Python bindings:

cmake -G "Visual Studio 16 2019" -B build -S . -DCMAKE_BUILD_CONFIG=Release ^
 -DCMAKE_PREFIX_PATH=\BAG -DCMAKE_INSTALL_PREFIX=\BAG -DSWIG_DIR=\BAG

Note: Use -G "Visual Studio 17 2022" for Visual Studio 2019.

Build and install:

cmake --build build
cmake --install build

Build Python wheels:

After building the C++ library in the build directory as above, you will be able to build a Python wheel for installing bagPy as follows:

python -m pip wheel -w .\wheel\ .\build\api\swig\python

Then install the wheel as follows:

for %%w in (.\wheel\bagPy-*.whl) do python -m pip install %%w

Running C++ tests in Visual Studio

The C++ unit tests are written with Catch2. There is no test harness at the moment. Using the Standard toolbar, choose bag_tests.exe as the Select Startup Item. Press F5 to run the tests.

If you are unable to run tests directly withing Visual Studio, the tests can be run manually. See appveyor.yml for details.

Running Python tests in Visual Studio

The Python tests do not use any unit test framework at the moment. Using the Standard toolbar, choose Current Document as the Select Startup Item. Open test_all.py (or any other test_*.py) in the python folder, and press F5 to run the tests.

If you are unable to run tests directly withing Visual Studio, the tests can be run manually. See appveyor.yml for details.