From 93297851ef3fa1ac83a1969d5e2f8318dd5c0419 Mon Sep 17 00:00:00 2001 From: "Matthew J. Milner" Date: Wed, 6 Nov 2024 01:37:30 +0100 Subject: [PATCH 1/3] Finish overhaul of build documentation Signed-off-by: Matthew J. Milner --- source/develop/build.md | 402 ++++++++++++++++++++++++++-------------- 1 file changed, 267 insertions(+), 135 deletions(-) diff --git a/source/develop/build.md b/source/develop/build.md index 84cd1137..a56b393b 100644 --- a/source/develop/build.md +++ b/source/develop/build.md @@ -15,14 +15,23 @@ It is also entirely possible to build each project individually without using th For simplicity, this guide will focus on the first approach. +The instructions in this guide assume that you know how to execute commands in a terminal. + :::{tip} Platform-specific instructions, guidance, and information is provided in expandable callouts marked by the respective icons {fab}`windows` {fab}`apple` {fab}`linux`. ::: +:::{admonition} Windows {fab}`windows` +:class: dropdown +For steps that require using the command line in a terminal, we recommend using Powershell 7 within Microsoft Terminal, which should be installed on your system already if you are using Windows 11 -- if not, you can get it from the [Microsoft Store](https://apps.microsoft.com/detail/9n0dx20hk701?ocid=webpdpshare). + +In recent versions of Powershell, Linux/macOS commands like `cd` are aliased to their Powershell equivalents, so all of the commands that you are instructed to carry out here should work fine. +::: + ## System -Only 64-bit operated systems are supported. +Only 64-bit operating systems are supported. The primary supported operating systems are those for which binaries are distributed: @@ -65,28 +74,39 @@ If you particularly wish to use Open Babel from your system, you will have to ha ### Development tools -The Open Chemistry project uses [Git](https://git-scm.com/) for version control, and [CMake](cmake.org) to direct the build process, so the first step is to ensure that you have both of these installed and set up on your system. +The Open Chemistry project uses [Git](https://git-scm.com/) for version control, so the first step is to ensure that you have it installed and set up on your system. +### Compiler and build system -### Compiler +:::{tip} +For those unfamiliar with compiling programs from source, or C++ ones in particular, building a modern C++ program typically uses three critical components: +- a compiler, which turns source code files into "object" files containing machine code +- a build tool, which automates the compilation and makes sure all compiler commands are run in the right order +- a build-system generator, which creates configuration files for a build tool based on a set of instructions; this makes building complex projects on multiple platforms with potentially different build tools and compilers much easier +::: -Broadly, you will need a C/C++ compiler that supports C++17. +Broadly, you will need a C/C++ compiler that supports C++17, a build tool such as [Ninja](https://ninja-build.org/), and [CMake](cmake.org). :::{admonition} Windows {fab}`windows` :class: dropdown -On Windows, [Visual Studio](https://visualstudio.microsoft.com/) is best supported, and it includes the MSVC compiler. +On Windows, the MSVC compiler is best supported, which is obtained as part of [Visual Studio](https://visualstudio.microsoft.com/). + +If, when installing Qt (see below), you choose to install "Developer and Designer Tools", this will install Ninja and CMake at the same time. +Otherwise, you will need to download and install them separately. + +CMake can also be installed using `winget install --exact --id Kitware.CMake`. ::: :::{admonition} macOS {fab}`apple` :class: dropdown -We recommend to use [Clang 17](https://clang.llvm.org/) on a Mac. +We recommend to use [Clang 17](https://clang.llvm.org/) on a Mac, with Ninja and CMake. ::: :::{admonition} Linux {fab}`linux` :class: dropdown -Both `gcc`/`g++` and `clang`/`clang++` generally work fine, as do both Unix Makefiles and Ninja for generating the Make files. +Both `gcc`/`g++` and `clang`/`clang++` generally work fine, as do both Unix Makefiles and Ninja. -If in doubt, stick to the combination of **gcc with Ninja**; this is what the automatic preparation of Avogadro binaries with GitHub actions uses, so if it is working successfully there, it should also work for you. +If you find you have problems compiling, stick to the combination of **gcc with Ninja**; this is what the automatic preparation of Avogadro binaries with GitHub actions uses, so if it is working successfully there, it should also work for you. ::: @@ -134,216 +154,328 @@ You should however make sure the following Qt modules are installed: - `QtWidgets` - `QtGui` - `QtOpenGL` +- `QtOpenGLWidgets` - `QtConcurrent` - `QtNetwork` - `QtSvg` -If building with Qt6, you will also need: - -- `QtOpenGLWidgets` -- `QtCore5Compat` - There are often separate `-devel` versions of each module as well, in which case, you will also need those. ::: -:::{admonition} Debian/Ubuntu-based distributions {fab}`linux` -:class: dropdown -You can install prerequisites with the following commands: +#### Other libraries -```bash -apt-get update && \ - apt-get install -y cmake curl build-essential qtbase5-dev qtdeclarative5-dev zlib1g-dev libxml2-dev git libqt5svg5-dev libqt5gui5 libqt5concurrent5 rapidjson && \ -``` -If you need a newer cmake version (replace aarch64 with your architecture or go to [CMake Releases](https://github.com/Kitware/CMake/releases/latest/)) -```bash -apt-get purge cmake && \ - curl -L -v -o /tmp/bin https://github.com/Kitware/CMake/releases/download/v3.26.5/cmake-3.26.5-linux-aarch64.sh && \ - chmod +x /tmp/bin && \ - cd /usr && \ - /tmp/bin -``` +##### Necessary + +:::{admonition} Windows {fab}`windows` +:class: dropdown +The main other library you will need to get is OpenSSL 3.3.2, either from the [Shining Light Productions website](https://slproweb.com/products/Win32OpenSSL.html) or using `winget install --exact --id ShiningLight.OpenSSL.Dev` ::: -:::{admonition} openSUSE Tumbleweed {fab}`linux` + +:::{admonition} Linux {fab}`linux` :class: dropdown -Many of the following may already be installed on your system. +You will need to install the following from your package manager, or similarly named equivalents: -```bash -sudo zypper refresh -sudo zypper install libqt5-qtbase libqt5-qtbase-devel libqt5-qtbase-common-devel glew-devel libOpenGL Spglib libarchive libxml2 glu readline xz libeigen3 libboost -``` +- `glu-devel` +- `libxml2-devel` +- `xz-devel` +- `readline-devel` +- `rapidjson-devel` -The `libqt5-qtbase*` patterns should include all the Qt dependencies you need, but it is worth checking that all the modules are installed still using: +You will also need `libopenssl` -- either v1.1 if are building with Qt 5, or >3.0 if you are building with Qt 6. -```bash -sudo zypper search libQt5 -``` +:::{warning} +For a successful build of Open Babel and therefore a successful build of Avogadro, the `rapidjson` version used cannot be the v1.1.0 release; it must have been patched to include at least [this patch](https://github.com/Tencent/rapidjson/pull/719) from 2016. +Your distro probably distributes a version including this patch, but if you have problems with the Open Babel build step, this may be why. +::: ::: -:::{admonition} Fedora {fab}`linux` -:class: dropdown -```bash -sudo dnf update -sudo dnf install -y cmake gcc gcc-g++ qt5-qtbase-devel zlib-devel libxml2-devel git curl qt5-qtsvg-devel kernel-devel glew-devel +(system-deps)= +##### Optional + +Many dependencies that Avogadro needs will be automatically downloaded and built during the build process. +This means you do not need to install them in advance, and versions will be used that the Avogadro team has determined are compatible. + +However, if you would prefer to use versions of these libraries that are installed on your system, you can build Avogadro with CMake flags of the style `-DUSE_SYSTEM_EIGEN`. +For some of them it is also possible to do without them altogether by telling Avogadro to build without the features that require it. + +This list includes: + +- `glew` +- `eigen` +- `OpenBabel` +- `spglib` +- `libarchive` +- `msgpackc` +- `mmtf-cpp` +- `libmsym` + +:::{warning} +If these libraries are not available on your machine, internet access will be required during the build step. + +See [Building offline](building-offline) for assistance in circumventing the need for an internet connection. ::: (cloning-repositories)= -## Cloning Repositories +## Getting the source code + +All further instructions will assume you are using `git` on the command line. + +As mentioned above, by far the easiest way to build Avogadro is to use the Open Chemistry repository as a basis, which contains the other projects as submodules. +Though building each submodule separately is possible, this "superbuild" approach is the only option we explicitly recommend and support. + +The submodules of the main repo can be cloned all in one go, or manually for finer control over which ones are downloaded. + -To clone the Open Chemistry repository that -contains the other projects as submodules, +### Recursive clone + +You can clone the main repo and all submodules automatically using: ```shell git clone --recursive https://github.com/OpenChemistry/openchemistry.git +git submodule update --init --recursive ``` -Or if you have a GitHub account with SSH key (e.g., for contributing -changes): +You can then later easily update all modules at once using: ```shell -git clone --recursive git@github.com:OpenChemistry/openchemistry.git +git submodule update --remote ``` -## Updating +See the [git submodule documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for further help. + -In order to update the repository from the openchemistry module you can -run, +### Manual clone + +You may prefer to only clone some of the submodules, or you may encounter problems with the recursive clone. +In this case, you are still recommended to clone the main repo, but take the following manual approach instead: ```shell -git pull -git submodule update --init +git clone https://github.com/OpenChemistry/openchemistry.git +cd openchemistry +git clone https://github.com/OpenChemistry/avogadrolibs.git +git clone https://github.com/OpenChemistry/avogadroapp.git ``` -## Prerequisites +This will overwrite each git submodule with a new normal git repository, and can be continued for as many submodules as desired. + + +#### Required and optional submodules + +To build the Avogadro desktop program, only the main Open Chemistry repo and the following submodules are strictly required: + +- `avogadrolibs` from https://github.com/OpenChemistry/avogadrolibs.git +- `avogadroapp` from https://github.com/OpenChemistry/avogadroapp.git -The Open Chemistry projects have a number of prerequisites, and these -vary by platform. On Windows Visual Studio 2017 is best supported. The -superbuild will attempt to build a number of dependencies, on Linux you -are likely best off installing these with your package manager, and on -macOS the homebrew package manager works well. +The following submodules are optional and add extra functionality to Avogadro: -We should add a package listing for various Linux distributions, but as -a guide you will need: +- `avogadro-i18n`, for languages other than US English, from https://github.com/OpenChemistry/avogadro-i18n.git +- `avogadrogenerators`, for generation of input files for computational packages, from https://github.com/OpenChemistry/avogenerators.git +- `crystals`, `fragments` and `molecules`, which populate the libraries of ready-to-use structures, from https://github.com/OpenChemistry/crystals.git, https://github.com/OpenChemistry/fragments.git, and https://github.com/OpenChemistry/molecules.git +- `avogadrodata`, which contains only a few files for testing, from https://github.com/OpenChemistry/avogadrodata.git +- `molequeue`, which lets you queue computational calculations from Avogadro, but is currently unmaintained, from https://github.com/OpenChemistry/molequeue.git -- a C/C++ compiler that supports C++17 -- OpenGL -- Qt 5.6+ -- CMake -- Python +More information on the contents of each can be found at [Project Structure](develop-structure). +## Building Avogadro + +The Open Chemistry project uses CMake to direct builds, so builds are configured and started using the `cmake` command. +This is done in two individual steps. + +Again, the following instructions assume you are using the "superbuild" approach. + + +### Configuring CMake + +It is recommended that you create the build tree outside of the source tree. + +To set up the build tree, first navigate to the directory containing the cloned `openchemistry` repository, then run the following command: + +```shell +cmake -DQT_VERSION=5 -DBUILD_MOLEQUEUE=OFF -S ./openchemistry -B ./build ``` -## Building +This will create a new directory, `build`, in the current directory next to `openchemistry`, then construct the build tree within it. + +To configure the build to build against Qt 6, use `-DQT_VERSION=6` instead. -It is recommended that you create a build tree outside of the source -tree. Assuming you are in the directory where you cloned the repository -the following commands will create a build tree, configure it and build. +To use a different compiler (such as `clang` on Linux when the default is `gcc`), add the flags `-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++`. + +To use a different build tool than whatever the default is on your system, add e.g. `-G Ninja`. + +:::{admonition} Windows {fab}`windows` +:class: dropdown +On Windows you may need to run with any or all of the following flags, with the paths adjusted as appropriate: ```shell -mkdir openchemistry-build -cd openchemistry-build -cmake ../openchemistry -cmake --build . --config Release +cmake -DQT_VERSION=5 -DBUILD_MOLEQUEUE=OFF -DQt5_DIR=C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5 -DCMAKE_TOOLCHAIN_FILE=C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5/Qt5Config.cmake -S ./openchemistry -B ./build ``` -You may wish to run cmake-gui in the build directory once it has been -configured. You can build against system libraries to avoid building -them (examples include Boost, Eigen, etc), and turn testing on globally -(ENABLE_TESTS) if you would like to ensure all tests are configured and -built for sub-projects. The --config argument to cmake --build is only -used on the Windows platform with MSVC, and can be removed elsewhere. +or if building against Qt 6: -(finding-qt-windows-generators)= +```shell +cmake -DQT_VERSION=6 -DBUILD_MOLEQUEUE=OFF -DQt6_DIR=C:/Qt/6.8.0/msvc2022_64/lib/cmake/Qt6 -DCMAKE_TOOLCHAIN_FILE=C:/Qt/6.8.0/msvc2022_64/lib/cmake/Qt6/Qt6Config.cmake -DCMAKE_PREFIX_PATH="C:/Qt/6.8.0/msvc2022_64/lib/cmake/Qt6;C:/Qt/6.8.0/msvc2022_64/lib/cmake" -DQT_ADDITIONAL_PACKAGES_PREFIX_PATH=C:/Qt/6.8.0/msvc2022_64 -S ./openchemistry -B ./build +``` +::: + + +#### Avogadro-specific CMake flags + +Avogadro's build process can be configured in a variety of ways by passing extra flags to the above `cmake` command. +In particular this is a good way to add extra functionality or to keep the build slim. +Here is a *non-exhaustive* list of some useful ones, with a short explanation and the default. +To use them, prefix them with `-D`. + +``` +BUILD_SHARED_LIBS "Build with shared libraries" ON +DOWNLOAD_TO_SOURCE_DIR "Download external dependency source archives to CMAKE_CURRENT_SOURCE_DIR/Downloads" OFF +DOWNLOAD_TO_BINARY_DIR "Download external dependency source archives to CMAKE_CURRENT_BINARY_DIR/Downloads" ON +# If both the above are set to `ON` then the SOURCE directory will be used +# If both the above are set to `OFF` then the user's personal Downloads folder will be used +USE_VTK "Enable libraries that use VTK in Avogadro" OFF +USE_HDF5 "Enable functionality that requires HDF5" OFF +USE_PYTHON "Enable functionality that requires Python" OFF +USE_YAEHMOP "Enable functionality that requires Yaehmop" OFF +USE_SYSTEM_{Dependency} "Use a system installation of {Dependency}" OFF +BUILD_MOLEQUEUE "Build the MoleQueue application" # Default depends on the Qt version +BUILD_AVOGADRO "Build the Avogadro 2 application" ON +BUILD_GPL_PLUGINS "Build GPL plugins, i.e. QTAIM in Avogadro" OFF +BUILD_DOCUMENTATION "Build documentation (Doxygen)" OFF +ENABLE_TESTING "Enable testing for Open Chemistry projects" OFF +``` + +The following should, when used, also be passed on to `avogadrolibs` to configure its build. +If the desktop application is being built, they are not particularly useful. + +``` +USE_OPENGL "Enable libraries that use OpenGL" ON +USE_LIBARCHIVE "Enable optional Libarchive features" ON +USE_LIBMSYM "Enable optional features using libmsym" ON +USE_SPGLIB "Enable optional features using spglib" ON +USE_MMTF "Enable optional features using mmtf" ON +``` + +Likewise, the following should be passed on to `avogadroapp` when given. + +``` +Avogadro_ENABLE_RPC "Enable RPC server" ON +``` + +For all available flags, see the `CMakeLists.txt` file in the top level of each project. + + +(building-offline)= +### Building offline + +In some situations it may not be possible or desirable to have the build process download the source code for the third-party dependencies during the build itself. + +One way to do this is to download the source code manually in advance and place the **compressed archives** in the *source* directory under `openchemistry/Downloads`. +This needs to be done for all the dependencies listed as [optional dependencies](system-deps). -### Finding Qt, Windows Generators +Then, when running the above `cmake` configure step, pass `-DDOWNLOAD_TO_SOURCE_DIR=ON` as one of the flags. -We go to great care to use Qt5_DIR as the base for all Qt 5 modules, so -setting the correct Qt5_DIR should result in a valid tree, you can also -use CMAKE_PREFIX_PATH to point at the install prefix of Qt. When setting -Qt5_DIR for Windows, using Qt 5.10.1 as an example, you should set the -variable to 'C:/Qt/Qt5.10.1/5.10.1/msvc2017_64/lib/cmake/Qt5' (without -the quotes). As you upgrade, you can usually just replace the version -(that occurs twice), you must also be careful to match the CMake -generator to the compiler and architecture on Windows, I recommend -'Visual Studio 15 2017 Win64', we no longer build/test 32 bit binaries -on any platform. +For this to work, you need to download the exact versions specified in `openchemistry/cmake/projects.cmake`, in the archive format expected. -(normal-development)= +The alternative is to turn off the use of each of these dependencies (see above for the necessary flags). -### Normal Development -You can also open the top-level CMakeLists.txt in Qt Creator, choose the -build location, have that configure and build and then open the -top-level CMakeLists.txt for each of the sub-projects. When setting the -build location choose the openchemistry-build/avogadrolibs for Avogadro, -openchemistry-build/molequeue for MoleQueue, etc. Once you have compiled -the top-level, for normal day-to-day development you are free to ignore -it and perform the majority of work in the project being developed. +### Starting the build + +Once everything is configured, actually building is a simple matter of running: + +```shell +cmake --build ./build +``` + +:::{admonition} Windows {fab}`windows` +:class: dropdown +On Windows you may wish to build a slimmed-down version of the program by running the build instead with: + +```shell +cmake --build ./build --config Release +``` +::: + +:::{admonition} Linux {fab}`linux` +:class: dropdown +If you used Ninja by passing `-G Ninja` in the configuration step, the build will automatically run in parallel. + +If you are using the default GNU Makefiles instead, the build will by default only use a single thread; to run in parallel use: + +```shell +cmake --build ./build -j 4 +``` + +where `4` is replaced by the number of threads you wish to use. +This results in significant speed-ups (roughly n times faster in the author's brief tests!). +::: + (build-tree-layout)= +## Layout of the build directory -## Build Tree Layout +Each submodule and project will initially be built within its own directories within the build directory, mirroring the source tree. -The build tree mirrors the source tree for most active projects. So -avogadrolibs is in the same relative path in the source and build trees. -For things such as Boost which are built from a source tarball they can -be found only in the build tree, and are under thirdparty/boost-prefix, -these projects are dependencies but are not expected to be edited in -place. +When using the "superbuild" strategy detailed here, all compiled libraries, objects, and binaries, as well as all supporting resources such as icons and metadata, are additionally installed to the `prefix` directory within the build directory, so that everything can be found in one convenient location. + +`prefix` contains the normal `include`, `bin`, `share` and `lib` subdirectories. + +:::{tip} +This can be used to inject an additional prefix in `CMAKE_PREFIX_PATH` to ensure that projects built by the superbuild are found by each other. + +It keeps the sub-projects relatively simple as they either find stuff in the prefix, or normal system paths. +::: -There is a prefix directory in the base of the build tree. This acts as -an install prefix for all projects, with the normal include, bin, share -and lib directories. This can be used to inject an additional prefix in -CMAKE_PREFIX_PATH to ensure projects build by the superbuild are found. -It keeps the sub-projects relatively simple as they either find stuff in -the prefix, or normal system paths. (running-executables)= +## Running executables -### Running Executables +It is recommended that you run the binaries from within the `prefix` directory in the build directory, e.g.: -It is recommended that you run the binaries from within the prefix -directory in the build tree. The top-level targets (avogadroapp, -molequeue, monogochem) all install to the prefix, if running make from -within the individual build trees run make install to ensure you are -using the latest version. On Linux and Windows running Avogadro 2 looks -like, +```shell +./build/prefix/bin/avogadro2 +``` + +or on Windows: ```shell -./openchemistry-build/prefix/bin/avogadro2 +./build/prefix/bin/avogadro2.exe ``` -On Mac, it might be: +On Mac on the other hand it might be: ```shell open /Users/your-user/openchemistry-build/avogadroapp/bin/Avogadro2.app ``` -Note that on Mac with Apple Silicon, you must sign all binaries before opening: +:::{admonition} macOS {fab}`apple` +:class: dropdown +Note that on macOS running on Apple Silicon, you must sign all binaries before opening: + ```shell codesign --force --deep -s "Developer ID Application: Username (Team ID)" prefix/Avogadro2.app ``` +::: + -(building-packages)= +(building-installers)= +### Building installers -### Building Packages +`avogadroapp` can build installers for Avogadro. -The molequeue and avogadroapps projects can build installers. -In order to do this you must cd into the appropriate subdirectory and -call make package. So to build the Avogadro 2 package, +In order to do this, move into the cd into the appropriate subdirectory within the build tree and call `make package`. So, to build the Avogadro 2 package: ```shell -cd avogadroapp +cd build/avogadroapp make package ``` -You may need to run cmake-gui, toggle advanced variables and -enable/disable packages you are interested in. They are prefixed by -CPACK, and can be toggled before calling make package. A binary -installer will be created in the build directory. +You may need to run cmake-gui, toggle advanced variables and enable/disable packages you are interested in. +They are prefixed by CPACK, and can be toggled before calling `make package`. +A binary installer will be created in the build directory. From bb30c96e13f7336c096dcce126ac53d206b2b4a7 Mon Sep 17 00:00:00 2001 From: Matt Milner Date: Wed, 6 Nov 2024 12:44:43 +0100 Subject: [PATCH 2/3] Add info on build types --- source/develop/build.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/source/develop/build.md b/source/develop/build.md index a56b393b..7e12981d 100644 --- a/source/develop/build.md +++ b/source/develop/build.md @@ -291,6 +291,7 @@ This is done in two individual steps. Again, the following instructions assume you are using the "superbuild" approach. +(configuring-build)= ### Configuring CMake It is recommended that you create the build tree outside of the source tree. @@ -325,6 +326,29 @@ cmake -DQT_VERSION=6 -DBUILD_MOLEQUEUE=OFF -DQt6_DIR=C:/Qt/6.8.0/msvc2022_64/lib ::: +(build-types)= +#### Build types + +By default, Avogadro will be built in "Debug" mode, which, as the name hints, makes it easier to track down bugs, but at the cost of an increased package size and less optimized (read: slower) code in comparison to "Release" mode + +To change the build type used, use the corresponding flag for `cmake` during the configuration step, e.g.: + +```shell +cmake -DQT_VERSION=5 -DBUILD_MOLEQUEUE=OFF -DCMAKE_BUILD_TYPE=Release -S ./openchemistry -B ./build +``` + +Possible build types for Avogadro are "Debug", "Release", "MinSizeRel" and "RelWithDebInfo". + +:::{admonition} Windows {fab}`windows` +:class: dropdown +On Windows the build type cannot be set in this way and must instead be indicated during the [build step](running-build) by e.g.: + +```shell +cmake --build ./build --config Release +``` +::: + + #### Avogadro-specific CMake flags Avogadro's build process can be configured in a variety of ways by passing extra flags to the above `cmake` command. @@ -385,6 +409,7 @@ For this to work, you need to download the exact versions specified in `openchem The alternative is to turn off the use of each of these dependencies (see above for the necessary flags). +(running-build)= ### Starting the build Once everything is configured, actually building is a simple matter of running: @@ -395,11 +420,13 @@ cmake --build ./build :::{admonition} Windows {fab}`windows` :class: dropdown -On Windows you may wish to build a slimmed-down version of the program by running the build instead with: +On Windows you may wish to build a better optimized version of the program by running the build instead with: ```shell cmake --build ./build --config Release ``` + +See [Build types](build-types) for more information. ::: :::{admonition} Linux {fab}`linux` From ce2702a4fab0ddfdcad708f77e619be1b5c9a214 Mon Sep 17 00:00:00 2001 From: Matt Milner Date: Wed, 6 Nov 2024 12:50:04 +0100 Subject: [PATCH 3/3] Give example of cmake flag usage --- source/develop/build.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/develop/build.md b/source/develop/build.md index 7e12981d..72683684 100644 --- a/source/develop/build.md +++ b/source/develop/build.md @@ -329,7 +329,7 @@ cmake -DQT_VERSION=6 -DBUILD_MOLEQUEUE=OFF -DQt6_DIR=C:/Qt/6.8.0/msvc2022_64/lib (build-types)= #### Build types -By default, Avogadro will be built in "Debug" mode, which, as the name hints, makes it easier to track down bugs, but at the cost of an increased package size and less optimized (read: slower) code in comparison to "Release" mode +By default, Avogadro will be built in "Debug" mode, which, as the name hints, makes it easier to track down bugs, but at the cost of an increased package size and less optimized (read: slower) code in comparison to "Release" mode. To change the build type used, use the corresponding flag for `cmake` during the configuration step, e.g.: @@ -354,7 +354,6 @@ cmake --build ./build --config Release Avogadro's build process can be configured in a variety of ways by passing extra flags to the above `cmake` command. In particular this is a good way to add extra functionality or to keep the build slim. Here is a *non-exhaustive* list of some useful ones, with a short explanation and the default. -To use them, prefix them with `-D`. ``` BUILD_SHARED_LIBS "Build with shared libraries" ON @@ -374,6 +373,13 @@ BUILD_DOCUMENTATION "Build documentation (Doxygen)" OFF ENABLE_TESTING "Enable testing for Open Chemistry projects" OFF ``` +To use them, prefix them with `-D`. +For example, to build with the VTK functionality and the automatically generated API documentation, you might run: + +```shell +cmake -DQT_VERSION=6 -DBUILD_MOLEQUEUE=OFF -DUSE_VTK=ON -DBUILD_DOCUMENTATION=ON -S ./openchemistry -B ./build +``` + The following should, when used, also be passed on to `avogadrolibs` to configure its build. If the desktop application is being built, they are not particularly useful.