Skip to content

Commit 3d9c870

Browse files
allnesallnes
authored
First update of documents (#170)
1 parent 2c01def commit 3d9c870

File tree

6 files changed

+154
-152
lines changed

6 files changed

+154
-152
lines changed

‎.gitignore

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
1-
build
1+
build*
22
out
33
mpich
4-
cmake-build-release*
5-
cmake-build-debug*
4+
cmake-build-*
65
.idea/
76
.vs/
87
.vscode/

‎README.md

Lines changed: 13 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -3,156 +3,20 @@
33

44
# Parallel Programming Course
55

6-
The following parallel programming technologies are considered in practice:
7-
* `MPI`
8-
* `OpenMP`
9-
* `TBB`
10-
* `std::thread`
11-
12-
## Rules for submissions
6+
### Parallel programming technologies:
7+
The following parallel programming technologies are considered in practice:
8+
* `Message Passing Interface (MPI)`
9+
* `OpenMP (Open Multi-Processing)`
10+
* `oneAPI Threading Building Blocks (oneTBB)`
11+
* `Multithreading in C++ (std::thread)`
12+
13+
### Rules for submissions:
1314
1. You are not supposed to trigger CI jobs by frequent updates of your pull request. First you should test you work locally with all the scripts (code style).
1415
* Respect others time and don't slow down the job queue
1516
2. Carefully check if the program can hang.
1617

17-
## 0. Download all submodules
18-
```
19-
git submodule update --init --recursive --depth=1
20-
```
21-
## 1. Set up your environment
22-
23-
### Code style analysis
24-
Please, follow [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
25-
26-
Code style is checked using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) tool.
27-
28-
### Parallel programming technologies
29-
### `MPI`
30-
* **Windows (MSVC)**:
31-
32-
[Installers link.](https://www.microsoft.com/en-us/download/details.aspx?id=105289) You have to install `msmpisdk.msi` and `msmpisetup.exe`.
33-
34-
* **Linux (`gcc` and `clang`)**:
35-
```
36-
sudo apt install -y mpich openmpi-bin libopenmpi-dev
37-
```
38-
* **MacOS (apple clang)**:
39-
```
40-
brew install open-mpi
41-
```
42-
43-
### `OpenMP`
44-
45-
`OpenMP` is included into `gcc` and `msvc`, but some components should be installed additionally:
46-
47-
* **Linux (`gcc` and `clang`)**:
48-
```
49-
sudo apt install -y libomp-dev
50-
```
51-
* **MacOS (`llvm`)**:
52-
```
53-
brew install llvm
54-
brew install libomp
55-
```
56-
57-
### `TBB`
58-
* **Windows (`MSVC`)**, **Linux (`gcc` and `clang`)**, **MacOS (apple clang)**:
59-
* Build as 3rdparty in the current project
60-
61-
### `std::thread`
62-
* `std::thread` is included into STL libraries.
63-
64-
## 2. Build the project with `CMake`
65-
Navigate to a source code folder.
66-
67-
1. Configure the build: `Makefile`, `.sln`, etc.
68-
69-
```
70-
mkdir build && cd build
71-
cmake -D USE_SEQ=ON -D USE_MPI=ON -D USE_OMP=ON -D USE_TBB=ON -D USE_STL=ON -D USE_FUNC_TESTS=ON -D USE_PERF_TESTS=ON -D CMAKE_BUILD_TYPE=Release ..
72-
```
73-
*Help on CMake keys:*
74-
- `-D USE_SEQ=ON` enable `Sequential` labs (based on OpenMP's CMakeLists.txt).
75-
- `-D USE_MPI=ON` enable `MPI` labs.
76-
- `-D USE_OMP=ON` enable `OpenMP` labs.
77-
- `-D USE_TBB=ON` enable `TBB` labs.
78-
- `-D USE_STL=ON` enable `std::thread` labs.
79-
- `-D USE_FUNC_TESTS=ON` enable functional tests.
80-
- `-D USE_PERF_TESTS=ON` enable performance tests.
81-
- `-D CMAKE_BUILD_TYPE=Release` required parameter for stable work of repo.
82-
83-
*A corresponding flag can be omitted if it's not needed.*
84-
85-
2. Build the project:
86-
```
87-
cmake --build . --config RELEASE
88-
```
89-
3. Check the task
90-
* Run `<project's folder>/build/bin`
91-
92-
## 3. How to submit you work
93-
* There are `mpi`, `omp`, `seq`, `stl`, `tbb` folders in `tasks` directory. Move to a folder of your task. Make a directory named `<last name>_<first letter of name>_<short task name>`. Example: `seq/nesterov_a_vector_sum`. Please name all tasks same name directory. If `seq` task named `seq/nesterov_a_vector_sum` then `omp` task need to be named `omp/nesterov_a_vector_sum`.
94-
* Go into the newly created folder and begin you work on the task. There must be only 4 directory with files:
95-
- `func_tests` - google tests directory with files for the functional tests of task.
96-
- `include` - a header files directory with function prototypes.
97-
- `perf_tests` - google tests directory with files for the performance tests of task. The number of tests must be 2 - `run_task` and `run_pipeline`.
98-
- `src` - a source files directory with functions realization.
99-
* We need to know that exist 10 executable files for running:
100-
- `<mpi, omp, seq, stl, tbb>_<func, perf>_tests` e.g. `omp_perf_tests` - executable file for performance tests of OpenMP practice tasks.
101-
* All prototypes and classes in the `include` directory must be namespace escaped, name your namespace in the following way:
102-
```
103-
namespace <last name>_<first letter of name>_<short task name>_<technology> {
104-
...
105-
}
106-
e.g.
107-
namespace nesterov_a_test_task_seq {
108-
109-
class TestTaskSequential : public ppc::core::Task {
110-
...
111-
};
112-
113-
} // namespace nesterov_a_test_task_seq
114-
```
115-
* Name your group of tests and current test in the following way:
116-
* for functional tests:
117-
```
118-
TEST(<last name>_<first letter of name>_<short task name>_<technology>, <any_name_of_test_case>) {
119-
...
120-
}
121-
e.g.
122-
TEST(nesterov_a_vector_sum_omp, test_sum) {
123-
...
124-
}
125-
```
126-
* for performance tests:
127-
```
128-
TEST(<last name>_<first letter of name>_<short task name>_<technology>, <type_of_performance_validation>) {
129-
...
130-
}
131-
e.g.
132-
TEST(nesterov_a_vector_sum_stl, test_pipeline_run) {
133-
...
134-
}
135-
TEST(nesterov_a_vector_sum_stl, test_task_run) {
136-
...
137-
}
138-
```
139-
* All tests need to be written without `main()` function
140-
* Name your pull request in the following way:
141-
* for tasks:
142-
```
143-
<Last Name First Name>. Task <Number of task>. Variant <Number of variant>. <Full name of task>.
144-
Нестеров Александр. Задача 1. Вариант 123. Сумма элементов вектора.
145-
```
146-
147-
* Provide the full task definition in pull request's description.
148-
149-
Example pull request is located in repo's pull requests.
150-
151-
* Work on your fork-repository. Keep your work on a separate branch and **NOT on `master`!!!**. Name you branch in the same way as your task's folder. To create a branch run:
152-
```
153-
git checkout -b nesterov_a_vector_sum
154-
```
155-
156-
*Failing to follow the rules makes the project build red.*
157-
158-
And finally,
18+
### Steps to create a task:
19+
1. [Download all submodules](docs/download.md)
20+
2. [Set up your environment](docs/environment.md)
21+
3. [Build the project with `CMake`](docs/build.md)
22+
4. [How to submit your current work](docs/submit_work.md)

‎docs/build.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Build the project with `CMake`
2+
3+
Navigate to a source code folder.
4+
5+
1. Configure the build: `Makefile`, `.sln`, etc.
6+
7+
```bash
8+
mkdir build && cd build
9+
cmake -D USE_SEQ=ON -D USE_MPI=ON -D USE_OMP=ON -D USE_TBB=ON -D USE_STL=ON -D USE_FUNC_TESTS=ON -D USE_PERF_TESTS=ON -D CMAKE_BUILD_TYPE=Release ..
10+
```
11+
*Help on CMake keys:*
12+
- `-D USE_SEQ=ON` enable `Sequential` labs (based on OpenMP's CMakeLists.txt).
13+
- `-D USE_MPI=ON` enable `MPI` labs.
14+
- `-D USE_OMP=ON` enable `OpenMP` labs.
15+
- `-D USE_TBB=ON` enable `TBB` labs.
16+
- `-D USE_STL=ON` enable `std::thread` labs.
17+
- `-D USE_FUNC_TESTS=ON` enable functional tests.
18+
- `-D USE_PERF_TESTS=ON` enable performance tests.
19+
- `-D CMAKE_BUILD_TYPE=Release` required parameter for stable work of repo.
20+
21+
*A corresponding flag can be omitted if it's not needed.*
22+
23+
2. Build the project:
24+
```bash
25+
cmake --build . --config Release --parallel
26+
```
27+
3. Check the task
28+
* Run `<project's folder>/build/bin`

‎docs/download.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## Download all submodules
2+
```bash
3+
git submodule update --init --recursive --depth=1
4+
```

‎docs/environment.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## Set up your environment
2+
3+
### Code style analysis
4+
Please, follow [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
5+
6+
Code style is checked using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) tool.
7+
8+
### Parallel programming technologies
9+
### `MPI`
10+
* **Windows (MSVC)**:
11+
12+
[Installers link.](https://www.microsoft.com/en-us/download/details.aspx?id=105289) You have to install `msmpisdk.msi` and `msmpisetup.exe`.
13+
14+
* **Linux (`gcc` and `clang`)**:
15+
```
16+
sudo apt install -y mpich openmpi-bin libopenmpi-dev
17+
```
18+
* **MacOS (apple clang)**:
19+
```
20+
brew install open-mpi
21+
```
22+
23+
### `OpenMP`
24+
25+
`OpenMP` is included into `gcc` and `msvc`, but some components should be installed additionally:
26+
27+
* **Linux (`gcc` and `clang`)**:
28+
```
29+
sudo apt install -y libomp-dev
30+
```
31+
* **MacOS (`llvm`)**:
32+
```
33+
brew install llvm
34+
brew install libomp
35+
```
36+
37+
### `TBB`
38+
* **Windows (`MSVC`)**, **Linux (`gcc` and `clang`)**, **MacOS (apple clang)**:
39+
* Build as 3rdparty in the current project
40+
41+
### `std::thread`
42+
* `std::thread` is included into STL libraries.

‎docs/submit_work.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
## How to submit your work
2+
3+
* There are `mpi`, `omp`, `seq`, `stl`, `tbb` folders in `tasks` directory. Move to a folder of your task. Make a directory named `<last name>_<first letter of name>_<short task name>`. Example: `seq/nesterov_a_vector_sum`. Please name all tasks **same** name directory. If `seq` task named `seq/nesterov_a_vector_sum` then `omp` task need to be named `omp/nesterov_a_vector_sum`.
4+
* Go into the newly created folder and begin you work on the task. There must be only 4 directory with files:
5+
- `func_tests` - google tests directory with files for the functional tests of task.
6+
- `include` - a header files directory with function prototypes.
7+
- `perf_tests` - google tests directory with files for the performance tests of task. The number of tests must be 2 - `run_task` and `run_pipeline`.
8+
- `src` - a source files directory with functions realization.
9+
* We need to know that exist 10 executable files for running:
10+
- `<mpi, omp, seq, stl, tbb>_<func, perf>_tests` e.g. `omp_perf_tests` - executable file for performance tests of OpenMP practice tasks.
11+
* All prototypes and classes in the `include` directory must be namespace escaped, name your namespace in the following way:
12+
```
13+
namespace <last name>_<first letter of name>_<short task name>_<technology> {
14+
...
15+
}
16+
e.g.
17+
namespace nesterov_a_test_task_seq {
18+
19+
class TestTaskSequential : public ppc::core::Task {
20+
...
21+
};
22+
23+
} // namespace nesterov_a_test_task_seq
24+
```
25+
* Name your group of tests and current test in the following way:
26+
* for functional tests (for maximum coverage):
27+
```
28+
TEST(<last name>_<first letter of name>_<short task name>_<technology>, <any_name_of_test_case>) {
29+
...
30+
}
31+
e.g.
32+
TEST(nesterov_a_vector_sum_omp, test_sum) {
33+
...
34+
}
35+
```
36+
* for performance tests (only 2 tests - `pipeline/task` - no more no less):
37+
```
38+
TEST(<last name>_<first letter of name>_<short task name>_<technology>, <type_of_performance_validation>) {
39+
...
40+
}
41+
e.g.
42+
TEST(nesterov_a_vector_sum_stl, test_pipeline_run) {
43+
...
44+
}
45+
TEST(nesterov_a_vector_sum_stl, test_task_run) {
46+
...
47+
}
48+
```
49+
* Name your pull request in the following way:
50+
* for tasks:
51+
```
52+
<Last Name First Name>. Task <Number of task>. Variant <Number of variant>. Technology <Name of technology>. <Full name of task>.
53+
Нестеров Александр. Задача 1. Вариант 123. Технология MPI. Сумма элементов вектора.
54+
```
55+
56+
* Provide the full task definition in pull request's description.
57+
58+
Example pull request is located in repo's pull requests.
59+
60+
* Work on your fork-repository. Keep your work on a separate branch and **NOT on `master`!!!**. Name you branch in the same way as your task's folder. To create a branch run:
61+
```
62+
git checkout -b nesterov_a_vector_sum_mpi
63+
```
64+
65+
*Failing to follow the rules makes the project build red.*

0 commit comments

Comments
 (0)