Skip to content
Snippets Groups Projects
Commit 0514509b authored by Atkins, Charles Vernon's avatar Atkins, Charles Vernon
Browse files

Re-work CMake build documentation

parent 6cc7ccd8
No related branches found
No related tags found
1 merge request!204Update build docs
Hide whitespace changes
Inline Side-by-side
Showing
with 138 additions and 91 deletions
ReadMe.md
+ 138
− 91
View file @ 0514509b
......@@ -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
...
$
```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment