Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
AnarManafov committed Sep 12, 2023
1 parent 4961dfe commit 878c957
Show file tree
Hide file tree
Showing 16 changed files with 290 additions and 52 deletions.
43 changes: 14 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,33 +21,18 @@ DDS:

## Documentation

- [User's manual](http://dds.gsi.de/documentation.html)
- [Installation](http://dds.gsi.de/doc/nightly/install.html)
- [Quick Start](http://dds.gsi.de/doc/nightly/quick-start.html)

## Building 3rd-party

### BOOST on macOS

```bash
./bootstrap.sh --prefix=[INSTALL DIR] --without-icu
./b2 --disable-icu --prefix=[INSTALL DIR] -j8 --layout=system threading=multi link=shared,static cxxstd=17 install

cd [INSTALL_DIR]/lib
find . -name '*.dylib' -exec bash -c 'nm=$(basename $1);install_name_tool $1 -id [INSTALL_DIR]/lib/$nm' -- {} \;
```

### BOOST on Linux
- [Requirements](./docs/requirements.md)
- [Installation](./docs/install.md)
- [Quick Start](./docs/quick-start.md)
- RMS plug-ins
- [localhost](./plugins/dds-submit-localhost/README.md)
- [ssh](./plugins/dds-submit-ssh/README.md)
- [slurm](./plugins/dds-submit-slurm/README.md)
- [lsf](./plugins/dds-submit-lsf/README.md)
- [pbs](./plugins/dds-submit-pbs/README.md)
- Additional docs
- [Build 3rd-party dependencies](./docs/3rd-party.md)

## Links

```bash
./bootstrap.sh --prefix=[INSTALL DIR] --without-icu
./b2 --disable-icu --prefix=[INSTALL DIR] -j8 --layout=system threading=multi link=shared,static cxxflags="-std=c++11" install
```

### clang-format on macOS

[LLVM binary builds](http://releases.llvm.org/download.html) An LLVM version 15.0.7 should be used: [Download](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.7)

### devtools-3 on CentOS

[Instructions](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/)
- [User's manual](http://dds.gsi.de/documentation.html)
Empty file added dds-submit/README.md
Empty file.
30 changes: 30 additions & 0 deletions docs/3rd-party.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Building 3rd-party

## BOOST Libs

### BOOST on macOS

```bash
./bootstrap.sh --prefix=[INSTALL DIR] --without-icu
./b2 --disable-icu --prefix=[INSTALL DIR] -j8 --layout=system threading=multi link=shared,static cxxstd=17 install

cd [INSTALL_DIR]/lib
find . -name '*.dylib' -exec bash -c 'nm=$(basename $1);install_name_tool $1 -id [INSTALL_DIR]/lib/$nm' -- {} \;
```

### BOOST on Linux

```bash
./bootstrap.sh --prefix=[INSTALL DIR] --without-icu
./b2 --disable-icu --prefix=[INSTALL DIR] -j8 --layout=system threading=multi link=shared,static cxxflags="-std=c++11" install
```

## clang-format

### clang-format on macOS

[LLVM binary builds](http://releases.llvm.org/download.html) An LLVM version 15.0.7 should be used: [Download](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.7)

### devtools-3 on CentOS

[Instructions](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/)
File renamed without changes.
File renamed without changes.
16 changes: 16 additions & 0 deletions docs/download.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Download

## Download location

Please, use [DDS's Download page](http://dds.gsi.de/download.html) to get the latest version and all other versions of DDS.

## DDS Version Number Scheme

DDS version has a form of ```MAJOR.MINOR(.PATCH)```, where:

```MAJOR``` - the major number is increased when there are significant jumps in functionality.
```MINOR``` - the minor number is incremented when only minor features or significant fixes have been added.
```PATCH``` - represents a number of commits (patches) to a current major.minor pair.

**Note**
The DDS's version scheme reflects the fact that DDS is both a production system and a research project. DDS uses odd minor version numbers to denote development releases and even minor version numbers to denote stable releases.
87 changes: 87 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Installation

## Step 1: Get the source

* **From DDS git repository**

```shell
git clone https://github.com/FairRootGroup/DDS.git DDS-master
cd ./DDS-master
```

* **From DDS source tarball**
Unpack DDS tarball:

```shell
tar -xzvf DDS-X.Y.Z-Source.tar.gz
```

The tar command will created a new directory ```./DDS-X.Y.Z-Source```, where ```X.Y.Z``` represents a version of DDS.

```shell
cd ./DDS-X.Y.Z-Source
```

## Step 2: Configure the source

You can adjust some configuration settings in the BuildSetup.cmake bootstrap file. The following is a list of variables:

| Variable | Variable |
|----------|----------|
| CMAKE_INSTALL_PREFIX | Install path prefix, prepended onto install directories.(default ```$HOME/DDS/<DDS_Version>```)|
| CMAKE_BUILD_TYPE | Set cmake build type. Possible options are: **None**, **Debug**, **Release**, **RelWithDebInfo**, **MinSizeRel** (default **Release**)|
| BUILD_DOCUMENTATION | Build source code documentation. Possible options are: **ON**/**OFF** (default **OFF**)|
| BUILD_TESTS | Build DDS tests. Possible options are: **ON**/**OFF** (default **OFF**)|

Now, prepare a build directory for an out-of-source build and configure the source:

```shell
mkdir build
cd build
cmake -C ../BuildSetup.cmake ..
```

**Note**
If for some reason, for example a missing dependency, configuration failed. After you get the issue fixed, right before starting the cmake command it is recommended to delete everything in the build directory recursively. This will guaranty a clean build every time the source configuration is restarted.

## Step 3: Build and install

Issue the following commands to build and install DDS:

```shell
make -j
make install
```

### Installation Prefix

Please note, that by default DDS will be installed in ```$HOME/DDS/X.Y.Z```, where ```X.Y.Z``` is a version of DDS. However users can change this behavior by setting the install prefix path in the bootstrap script BuildSetup.cmake. Just uncomment the setting of *CMAKE_INSTALL_PREFIX* variable and change dummy *MY_PATH_HERE* to a desired path.

### WN package

Users have a possibility to additionally build DDS worker package for the local platform. In case if you have same OS types on all of the target machines and don't want to use WN packages from the DDS binary repository, just issue:
```shell
make -j wn_bin
make install
```
The commands will build and install a DDS worker package for the given platform.
We also recommend to build boost without [the icu library](http://site.icu-project.org/) support. This will reduce the size of the WN package dramatically. The following is boost build options you can use to switch of icu:
```shell
./bootstrap.sh --without-icu ...
./b2 --disable-icu ...
```
## Step 4: DDS Environment
In order to enable DDS's environment you need to source the DDS_env.sh script. Change to your newly installed DDS directory and issue:

```shell
cd [DDS INSTALL DIRECTORY]
source DDS_env.sh
```

You need to source this script every time before using DDS in a new system shell. Simplify it by sourcing the script in your bash profile.
40 changes: 40 additions & 0 deletions docs/quick-start.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Quick Start

1. [Download DDS source tarball](./download.md).
1. [Install DDS from source](./install.md).
1.Enable DDS environment.

```shell
cd <DDS INSTALLATION location>
source DDS_env.sh
```

1.Start DDS commander server.

```shell
dds-session start
```

1.Deploy 1 DDS agent with 50 task slots on the localhost.

```shell
dds-submit --rms localhost --slots 50
```

1.Use dds-info to find out a number of agents, which are online.

```shell
dds-info -n
```

1.Use dds-info to check detailed information about agents.

```shell
dds-info -l
```

1.Set and activate the topology.

```shell
dds-topology --activate $DDS_LOCATION/tutorials/tutorial1/tutorial1_topo.xml
```
23 changes: 23 additions & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Requirements

## Server/UI

DDS UI/Server/WN run on Linux and Mac OS X.

### General requirements

- Incoming connection on dds-commander port (configurable)
- a C++11 compiler
- [cmake](http://www.cmake.org/) 3.23.1 or higher
- [BOOST](http://www.boost.org/) 1.75 or higher (built by a C++11 compiler, with C++11 enabled)
- shell: [BASH (or a compatible one)](http://en.wikipedia.org/wiki/Bash_(Unix_shell))

### Additional requirements for the SSH plug-in

- A public key access (or password less, via ssh-agend, for example) to destination worker nodes.

## Agents

- Outgoing connection on dds-commander's port range (configurable).
This is required by dds-agent to be able to connect to DDS commander server
- shell: [BASH (or a compatible one)](http://en.wikipedia.org/wiki/Bash_(Unix_shell))
16 changes: 0 additions & 16 deletions documentation/README.md

This file was deleted.

7 changes: 0 additions & 7 deletions documentation/mainpage.md

This file was deleted.

15 changes: 15 additions & 0 deletions plugins/dds-submit-localhost/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# localhost RMS plug-in

## Introduction

DDS's localhost plug-in is capable to deploy DDS agents on a local machine. Unlike SSH plug-in, localhost plug-in doesn't require a password-less access (public key, ssh agent, etc.).
The configuration file is not required for localhost plug-in.
The plug-in spawns 1 agent with a defined number of task slots on the local machine only. Just use [dds-submit --slots X](../../dds-submit/README.md), where X is a desired number of task slots.

## Usage example

Call using a local system only to spawn 1 DDS agent with 10 task slots:

```shell
dds-submit -r localhost --slots 10
```
Empty file.
1 change: 1 addition & 0 deletions plugins/dds-submit-pbs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# PBS RMS plug-in
63 changes: 63 additions & 0 deletions plugins/dds-submit-slurm/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# SLURM RMS plug-in

## Sandbox directory

If your home directory is not shared on the SLURM cluster, then you must define a sandbox directory, which DDS will use to store SLURM job script and all jobs' working directories will be also located there. Please note, that at the moment DDS doesn't clean jobs' working directories, therefore you are responsible to remove them if needed.

In order to set sandbox directory a DDS global option ```server.sandbox_dir``` have to be changed, which is located in the DDS configuration file ```DDS.cfg``` (default location: ```$HOME/.DDS/DDS.cfg```)

## User configuration

Using [dds-submit -c My_SLURM.cfg](../../dds-submit/README.md) command you can provide additional configuration options for DDS SLURM jobs.
For example, the following command will submit 10 DDS agents (each with 50 task slots) and will use additional SLURM configuration options provided in the ```My_SLURM.cfg```:

```shell
dds-submit -r slurm -n 10 --slots 50 -c My_SLURM.cfg
```

**Note**
The content of the custom SLURM job configuration file can be any ```sbatch``` parameter, except ```srun``` and ```--array```.

For example, My_SLURM.cfg can contain:

```bash
#SBATCH -A "account"
#SBATCH --time=00:30:00
```

## Usage example

Submit 10 DDS agents to SLURM cluster. On the SLURM submitter machine execute:

```shell
$ dds-submit -r slurm -n 10

dds-submit: Contacting DDS commander on lxbk0200.gsi.de:20001 ...
dds-submit: Connection established.
dds-submit: Requesting server to process job submission...
dds-submit: Server reports: Creating new worker package...
dds-submit: Server reports: RMS plug-in: /u/manafov/DDS/1.1.61.g474ddc6/plugins/dds-submit-slurm/dds-submit-slurm
dds-submit: Server reports: Initializing RMS plug-in...
dds-submit: Server reports: RMS plug-in is online. Startup time: 17ms.
dds-submit: Server reports: Plug-in: Generating SLURM Job script...
dds-submit: Server reports: Plug-in: Preparing job submission...
dds-submit: Server reports: Plug-in: pipe log engine: Submitting DDS Job on the SLURM cluster...

dds-submit: Server reports: Plug-in: pipe log engine: SLURM: Submitted batch job 9539993

dds-submit: Server reports: Plug-in: DDS agents have been submitted
```

Check the status of your SLURM jobs:

```shell
scontrol show job 9539993
```

Check the status of your DDS agents:

```shell
dds-info -ln
```

Once agents are online, use DDS as normal.
1 change: 1 addition & 0 deletions plugins/dds-submit-ssh/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# SSH RMS plug-in

0 comments on commit 878c957

Please sign in to comment.