Unverified Commit ce71830d authored by Atkins, Charles Vernon's avatar Atkins, Charles Vernon Committed by GitHub
Browse files

Merge pull request #1085 from chuckatkins/update-cmake-docs 

Update cmake docs
parents 6e16acd4 c2bcbb29

ReadMe.md

+50 −47
Original line number Diff line number Diff line
@@ -59,35 +59,39 @@ $ mkdir build 
3. Configure the project with CMake:



```bash

$ mkdir adios2

$ cd adios2

$ git clone https://github.com/ornladios/adios2.git source

$ mkdir build

$ cd build

$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.2.0/gnu/openmpi ../ADIOS2

-- The C compiler identification is GNU 6.3.1

-- The CXX compiler identification is GNU 6.3.1

$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.3.0/gnu/openmpi ../source

-- The C compiler identification is GNU 7.3.0

-- The CXX compiler identification is GNU 7.3.0

...



ADIOS2 build configuration:

  ADIOS Version: 2.2.0

  C++ Compiler : GNU 5.4.0 

    /usr/bin/c++

  C++ Compiler : GNU 7.3.0 

    /opt/ohpc/pub/compiler/gcc/7.3.0/bin/g++



  Fortran Compiler : GNU 5.4.0 

    /usr/bin/gfortran

  Fortran Compiler : GNU 7.3.0 

    /opt/ohpc/pub/compiler/gcc/7.3.0/bin/gfortran



  Installation prefix: /opt/adios2

  Installation prefix: /opt/adios2/2.3.0/gnu/openmpi

        bin: bin

        lib: lib

    include: include

      cmake: lib/cmake/adios2

     python: lib/python3.5/site-packages



  Features:

    Library Type: shared

    Build Type:   Debug

    Build Type:   Release

    Testing: ON

    Build Options:

      BZip2    : ON

      ZFP      : ON

      SZ       : ON

      ZFP      : OFF

      SZ       : OFF

      MGARD    : OFF

      MPI      : ON

      DataMan  : ON

      SST      : ON
@@ -96,17 +100,18 @@ ADIOS2 build configuration: 
      Python   : ON

      Fortran  : ON

      SysVShMem: ON

      Endian_Reverse: OFF



-- Configuring done

-- Generating done

-- Build files have been written to: /home/chuck/Code/adios2/build

$

-- Build files have been written to: /home/chuck/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.                                                              |
@@ -122,12 +127,11 @@ Note: The `ADIOS2_USE_HDF5` option requires the use of a matching serial or para 
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                                |

| :------------------------- | :-------------------------------------------------------: | :------------------------------------------------------------------------------------ |

| :---------------------: | :-------------------------------------------------------: | :----------------------------------------: |

| `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.                                                                     |

| `ADIOS2_BUILD_EXAMPLE   | **`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:
@@ -140,13 +144,12 @@ $ make -j8 


```bash

$ ctest

Test project /home/chuck/Code/adios2/build

      Test project /home/wfg/workspace/build

        Start   1: ADIOSInterfaceWriteTest.DefineVar_int8_t_1x10

  1/113 Test   #1: ADIOSInterfaceWriteTest.DefineVar_int8_t_1x10 ............................   Passed    0.07 sec

        Start   2: ADIOSInterfaceWriteTest.DefineVar_int16_t_1x10

  2/113 Test   #2: ADIOSInterfaceWriteTest.DefineVar_int16_t_1x10 ...........................   Passed    0.07 sec

        Start   3: ADIOSInterfaceWriteTest.DefineVar_int32_t_1x10

Test project /home/chuck/adios2/build

       Start   1: HeatTransfer.BPFile.Write.MxM

  1/295 Test   #1: HeatTransfer.BPFile.Write.MxM ............................................   Passed    1.25 sec

        Start   2: HeatTransfer.BPFile.Read.MxM

  2/295 Test   #2: HeatTransfer.BPFile.Read.MxM .............................................   Passed    0.55 sec

        Start   3: HeatTransfer.BPFile.Dump.MxM

  ...

  

$
@@ -161,16 +164,16 @@ $ make install 
[ 68%] Built target adios2py

...

Install the project...

-- Install configuration: "Debug"

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/include/adios2/ADIOSConfig.h

-- Install configuration: "Release"

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/include/adios2/ADIOSConfig.h

...

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/bin/adios2-config

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/bin/adios2-config

...

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/include/adios2.h

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/include/adios2.h

...

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/lib/libadios2.so.2.0.0

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/lib/libadios2.so.2

-- Installing: /opt/adios2/2.2.0/gnu/openmpi/lib/libadios2.so

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/lib/libadios2.so.2.3.0

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/lib/libadios2.so.2

-- Installing: /opt/adios2/2.3.0/gnu/openmpi/lib/libadios2.so

...

$

```

docs/ReadMe.md

+1 −1
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 


# Generate User Guide in html with Sphinx



This user guide is hosted in readthedocs: https://adios2-adaptable-io-system-version-2.readthedocs.io/en/latest/

This user guide is hosted in readthedocs: https://adios2.readthedocs.io/en/latest/

 

Python v2.7 or above is required to build the Sphinx based user guide. Sphinx can be downloaded using pip `pip install sphinx`. In addition:

docs/user_guide/source/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -13,6 +13,7 @@ Funded by the `Exascale Computing Project (ECP) <https://www.exascaleproject.org 


   introduction/introduction

   installation/installation

   using/using

   components/components

   engines/engines

   api_full/api_full

docs/user_guide/source/installation/cmake.rst

+242 −63

File changed.

Preview size limit exceeded, changes collapsed.

docs/user_guide/source/using/using.rst

0 → 100644
+28 −0
Original line number Diff line number Diff line 
############

Using ADIOS in your own projects

############



ADIOS2 uses `CMake <https://cmake.org/>`_ version 3.6 or above.  You consume it directly from another CMake project, use the `find_package` call and set the `ADIOS2_ROOT` or `ADISO2_DIR` environment variables to the install prefix for adios:



.. code-block:: cmake

    cmake_minimum_required(VERSION 3.6)

    project(MySimulation C CXX)



    find_package(MPI REQUIRED)

    find_package(ADIOS2 REQUIRED)



    ...

    add_library(my_library src1.cxx src2.cxx...)

    target_link_libraries(my_library PRIVATE adios2::adios2 MPI::MPI_C ...)





Or if you're not using CMake then you can manually get the necessary compile and link flags for your project using the adios2-config tool from the installation folder:



.. code-block:: bash

    $ /path/to/install-prefix/bin/adios2-config --cxxflags

    ADIOS2_DIR: /home/khq.kitware.com/chuck.atkins/Code/adios2/install/master

-isystem /home/khq.kitware.com/chuck.atkins/Code/adios2/install/master/include -isystem /opt/ohpc/pub/mpi/openmpi3-gnu7/3.1.0/include -pthread -std=gnu++11

    $ /path/to/install-prefix/bin/adios2-config --cxxlibs

    ADIOS2_DIR: /home/khq.kitware.com/chuck.atkins/Code/adios2/install/master

-Wl,-rpath,/home/khq.kitware.com/chuck.atkins/Code/adios2/install/master/lib:/opt/ohpc/pub/mpi/openmpi3-gnu7/3.1.0/lib /home/khq.kitware.com/chuck.atkins/Code/adios2/install/master/lib/libadios2.so.2.2.0 -pthread -Wl,-rpath -Wl,/opt/ohpc/pub/mpi/openmpi3-gnu7/3.1.0/lib -Wl,--enable-new-dtags -pthread /opt/ohpc/pub/mpi/openmpi3-gnu7/3.1.0/lib/libmpi.so -Wl,-rpath-link,/home/khq.kitware.com/chuck.atkins/Code/adios2/install/master/lib