From 0514509bacb2f7576507a17dd4abbbd20d5910e2 Mon Sep 17 00:00:00 2001 From: Chuck Atkins <chuck.atkins@kitware.com> Date: Fri, 30 Jun 2017 13:27:19 -0400 Subject: [PATCH] Re-work CMake build documentation --- ReadMe.md | 229 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 138 insertions(+), 91 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 5c3f7acd0..5781eadd3 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -9,10 +9,10 @@ Copyright.txt for more details. ## Directory layout * cmake - Project specific CMake modules -* examples - ADIOS Examples -* include - Public header files +* examples - ADIOS2 Examples * scripts - Project maintenance and development scripts -* source - Main ADIOS source +* source - Main ADIOS2 source +* bindings - Additional language bindings (currently only Python is available) * testing - Tests ## Documentation @@ -24,102 +24,149 @@ instructions under: [doc/ReadMe.md](doc/ReadMe.md) ## Getting Started -ADIOS 2.0.0.alpha uses CMake for its build environment. CMake expects projects -to use "out-of-source" builds, which means keeping a separate build and source -directory (different from autotools, which usually uses an in-source build). +ADIOS2 uses CMake for its build environment. CMake expects projects +to use "out-of-source" builds, which means keeping a separate build and source +directory (different from autotools, which usually uses an in-source build). -To build ADIOS: +To build ADIOS2: 1. Clone the repository: - - ``` - $ mkdir ADIOS2 - $ cd ADIOS2 - $ git clone https://github.com/ornladios/adios2.git source - ``` - + +```bash +$ mkdir adios2 +$ cd adios2 +$ git clone https://github.com/ornladios/adios2.git source +``` + 2. Create a separate build directory: - ``` - $ mkdir build - ``` - -3. ***Configure the project with CMake***. The following options can be specified as `ON` or `OFF` with cmake's `-DVAR=VALUE` syntax, where VAR options are: - - * `ADIOS2_BUILD_SHARED_LIBS` - Build shared libraries (`OFF` for static) - * `ADIOS2_BUILD_EXAMPLES ` - Build examples - * `ADIOS2_BUILD_TESTING ` - Build test code - * `ADIOS2_USE_MPI ` - Enable MPI - * `ADIOS2_USE_BZip2 ` - Enable [BZip2](http://www.bzip.org/) compression (not implemented) - * `ADIOS2_USE_ZFP ` - Enable [ZFP](https://github.com/LLNL/zfp) compression (not implemented) - * `ADIOS2_USE_ADIOS1 ` - Enable the [ADIOS 1.x](https://www.olcf.ornl.gov/center-projects/adios/) engine - * `ADIOS2_USE_DataMan ` - Enable the DataMan engine for WAN transports - * `ADIOS2_USE_Python ` - Enable the Python bindings - - ***Important, automatic discovery***: ADIOS 2.0 CMake has an AUTO discovery "ON" default option. If a certain - dependency is found in the system installation path (_e.g._ /usr/), not a custom one (_e.g._ /home , /opt ) it will turn on installation for that dependency automatically - - In addition, the -DCMAKE_VAR frequent options can be selected: - * `CMAKE_INSTALL_PREFIX ` - Prefix location for installation with `make install`, default depends on system (_e.g._ /usr/local) - * `CMAKE_BUILD_TYPE ` - Debug (default, debugging symbols), or Release (compiler optimizations) - - Example: - ``` - $ cd build - $ cmake -DADIOS_USE_MPI=ON -DCMAKE_BUILD_TYPE=Debug ../ADIOS2 - -- The C compiler identification is GNU 6.3.1 - -- The CXX compiler identification is GNU 6.3.1 - -- Check for working C compiler: /usr/bin/cc - -- Check for working C compiler: /usr/bin/cc -- works - -- Detecting C compiler ABI info - -- Detecting C compiler ABI info - done - -- Detecting C compile features - -- Detecting C compile features - done - -- Check for working CXX compiler: /usr/bin/c++ - -- Check for working CXX compiler: /usr/bin/c++ -- works - -- Detecting CXX compiler ABI info - -- Detecting CXX compiler ABI info - done - -- Detecting CXX compile features - -- Detecting CXX compile features - done - -- Found BZip2: /usr/lib64/libbz2.so (found version "1.0.6") - -- Looking for BZ2_bzCompressInit - -- Looking for BZ2_bzCompressInit - found - - ADIOS2 build configuration: - C++ Compiler: GNU 6.3.1 - /usr/bin/c++ - - Installation prefix: /usr/local - Features: - Library Type: shared - Build Type: Debug - Testing: ON - MPI: OFF - BZip2: OFF - ADIOS1: OFF - DataMan: OFF - - -- Configuring done - -- Generating done - -- Build files have been written to: /path/to/adios/build - $ - ``` - - You can also use CMake's curses-base UI with `ccmake ../source`. +```bash +$ mkdir build +``` + +3. Configure the project with CMake: + +```bash +$ cd build +$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.0.0/gnu/openmpi ../source +-- The C compiler identification is GNU 6.3.1 +-- The CXX compiler identification is GNU 6.3.1 +... + +ADIOS2 build configuration: + ADIOS Version: 2.0.0 + C++ Compiler : GNU 6.3.1 + /usr/bin/c++ + + Installation prefix: /opt/adios2/2.0.0/gnu/openmpi + Features: + Library Type: shared + Build Type: Debug + Testing: ON + Build Options: + BZip2 : ON + ZFP : OFF + MPI : ON + DataMan : ON + ZeroMQ : ON + HDF5 : ON + ADIOS1 : OFF + Python : ON + SysVShMem: ON + +-- Configuring done +-- Generating done +-- Build files have been written to: /home/chuck/Code/adios2/build +$ +``` + +The following options can be specified with CMake's `-DVAR=VALUE` syntax to control which features get enabled or disabled: + +| CMake Option | Values | Description | +| :------------------- | :-------------------------: | :------------------------------------------------------------------------------- | +| `ADIOS2_USE_BZip2` | **`AUTO`**/``ON``/``OFF`` | Enable [BZip2](http://www.bzip.org/) compression (not implemented). | +| `ADIOS2_USE_ZFP` | **`AUTO`**/``ON``/``OFF`` | Enable [ZFP](https://github.com/LLNL/zfp) compression (not implemented). | +| `ADIOS2_USE_MPI` | **`AUTO`**/``ON``/``OFF`` | Enable MPI. | +| `ADIOS2_USE_DataMan` | **`AUTO`**/``ON``/``OFF`` | Enable the DataMan engine for WAN transports. | +| `ADIOS2_USE_ZeroMQ` | **`AUTO`**/``ON``/``OFF`` | Enable ZeroMQ for the DataMan engine. | +| `ADIOS2_USE_HDF5` | **`AUTO`**/``ON``/``OFF`` | Enable the [HDF5](https://www.hdfgroup.org) engine. | +| `ADIOS2_USE_ADIOS1` | **`AUTO`**/``ON``/``OFF`` | Enable the [ADIOS 1.x](https://www.olcf.ornl.gov/center-projects/adios/) engine. | +| `ADIOS2_USE_Python` | **`AUTO`**/``ON``/``OFF`` | Enable the Python >= 2.7 bindings. | + +Note: The `ADIOS2_USE_HDF5` and `ADIOS2_USE_ADIOS1` options require the use of a matching serial or parallel version depending on whether `ADIOS2_USE_MPI` is enabled. SImilary, enabling MPI and Python bindings requires the presence of `mpi4py`. + +In addition to the `ADIOS2_USE_Feature` options, the following options are also available to control how the library get's built: + +| CMake Options | Values | Description | +| :------------------------- | :-------------------------------------------------------: | :------------------------------------------------------------------------------------ | +| `ADIOS2_BUILD_SHARED_LIBS` | **`ON`**/`OFF` | Build shared libraries. | +| `ADIOS2_ENABLE_PIC` | **`ON`**/`OFF` | Enable Position Independent Code for static libraries. | +| `ADIOS2_BUILD_EXAMPLES` | **`ON`**/`OFF` | Build examples. | +| `ADIOS2_BUILD_TESTING` | **`ON`**/`OFF` | Build test code. | +| `CMAKE_INSTALL_PREFIX` | /path/to/install (`/usr/local`) | Install location. | +| `CMAKE_BUILD_TYPE` | **`Debug`** / `Release` / `RelWithDebInfo` / `MinSizeRel` | The level of compiler optimization to use. | 4. Compile: - ``` - $ make -j8 - ``` +```bash +$ make -j8 +``` 5. Run tests: - ``` - $ make test - ``` - -## Developers - -To summit changes to ADIOS 2.0: please see the [wiki's](https://github.com/ornladios/ADIOS2/wiki) -Contributing to ADIOS section, or the local [Contributors Guide](Contributing.md). +```bash +$ ctest +Test project /home/chuck/Code/adios2/build + Start 1: ADIOSInterfaceWriteTest.DefineVarChar1x10 + 1/31 Test #1: ADIOSInterfaceWriteTest.DefineVarChar1x10 .............. Passed 0.00 sec + Start 2: ADIOSInterfaceWriteTest.DefineVarShort1x10 + 2/31 Test #2: ADIOSInterfaceWriteTest.DefineVarShort1x10 ............. Passed 0.00 sec +... + Start 21: HDF5WriteReadTest.ADIOS2HDF5WriteHDF5Read1D8 +21/31 Test #21: HDF5WriteReadTest.ADIOS2HDF5WriteHDF5Read1D8 ........... Passed 0.01 sec + Start 22: HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8 +22/31 Test #22: HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8 .....***Not Run (Disabled) 0.00 sec + Start 23: HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8 +23/31 Test #23: HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8 ...........***Not Run (Disabled) 0.00 sec +... + Start 30: PythonBPWrite +30/31 Test #30: PythonBPWrite .......................................... Passed 0.12 sec + Start 31: XMLConfigTest.TwoIOs +31/31 Test #31: XMLConfigTest.TwoIOs ................................... Passed 0.01 sec + +100% tests passed, 0 tests failed out of 25 + +Total Test time (real) = 0.29 sec + +The following tests did not run: + 22 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8 (Disabled) + 23 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8 (Disabled) + 25 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read2D2x4 (Disabled) + 26 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read2D2x4 (Disabled) + 28 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read2D4x2 (Disabled) + 29 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read2D4x2 (Disabled) +$ +``` + +6. Install: +``` +$ make install +[ 7%] Built target adios2sys_objects +... +[ 61%] Built target adios2 +[ 68%] Built target adios2py +... +Install the project... +-- Install configuration: "Debug" +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/include/adios2/ADIOSConfig.h +... +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/bin/adios2-config +... +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/include/adios2.h +... +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so.2.0.0 +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so.2 +-- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so +... +$ +``` -- GitLab