Skip to content

Commit

Permalink
Merge pull request SENSES-Lab-Sapienza#4 from emanuelegiona/main
Browse files Browse the repository at this point in the history 
New images released; fixes issues related to GCC mismatch and WOSS/Ne…
  • Loading branch information
@emanuelegiona
emanuelegiona authored Oct 11, 2023
2 parents aeccc43 + 70f48d4 commit 0393319
Show file tree
Hide file tree
Showing 28 changed files with 2,838 additions and 159 deletions.
100 changes: 100 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Changelog

## Release v3.0.0

[Link to release][v300]

**Users are urged to update to any of the images hereby released.**

Introduced support to new OS, ns-3, and WOSS versions:

- OS: Ubuntu 20.04 LTS

- ns-3: 3.40

- WOSS: 1.12.5

Differently from previous releases, new images pair all supported ns-3 versions with WOSS 1.12.5.

This release fixes these critical issues:

- GCC version mismatch between WOSS requirements, WOSS library and ns-3

Starting from ns-3.36, GCC 8 became the minimum supported version.
More details can be found at [this page][gcc-8-issue].

Images released prior to v3.0.0 bundled ns-3.37 with WOSS using Ubuntu 18.04 LTS as base image, causing the issue.
Indeed, while ns-3 was being built with GCC 8, WOSS library and its dependencies were instead built and linked using the system-default GCC 7.5.0.
During simulation execution, segmentation faults were occurring due such mismatch in GCC versions.

In order to fix this issue, upgrading to Ubuntu 20.04 LTS is a quick solution since the system-default GCC version is 9.3.0.
As a result, ns-3.37 images based on Ubuntu 18.04 should NOT be used, in favor of the hereby provided one, which is instead based on Ubuntu 20.04 LTS.

- Situational WOSS crashes (due to HDF5 and/or NetCDF-C)

WOSS users designing simulations with long running time and/or large networks might encounter crashes from the NetCDF library.
More details can be found at [this page][woss-netcdf-crash].

In order to fix this issue, upgrading all WOSS requirements to their latest versions proved to be a solution to this problem.
As a result, all images prior to v3.0.0 should NOT be used in case you encounter this problem during your WOSS-based simulations.

Minor changes:

- Instructions in each `Dockerfile` are re-arranged to reduce layers

## Release v2.0.1

[Link to release][v201]

Various updates to all supported images (revision `r2`):

- improved `Dockerfile` with: parametrized ns-3 and WOSS versions, separation of `debug` and `optimized` build directories

- uniformed functionality of scripts `build-debug.sh` and `build-optimized.sh` across ns-3 versions

- introduced utility `Makefile` to images released in v1.0.0

## Release v1.1.0

[Link to release][v110]

Introduced support to new ns-3 and WOSS versions:

- ns-3: 3.37

- WOSS: 1.12.4

ns-3 adopted the CMake build system starting from 3.36 release.

As a result, a new container filesystem has been designed, featuring separate ns-3 build directories depending on the profiles: `ns-3.37-debug` and `ns-3.37-optimized` directories respectively contain identical ns-3 source tree, permanently kept in their specific build profile.

More details can be found at [this page][ns3-cmake].

## Release v1.0.0

[Link to release][v100]

Initial release.

Supported versions:

- OS: Ubuntu 18.04 LTS

- ns-3: from 3.33 to 3.35

- WOSS: from 1.12.0 to 1.12.2



<!--- Releases --->
[v100]: https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker/releases/tag/v1.0.0
[v110]: https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker/releases/tag/v1.1.0
[v201]: https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker/releases/tag/v2.0.1
[v300]: https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker/releases/tag/v3.0.0

<!--- v1.1.0 --->
[ns3-cmake]: https://www.nsnam.org/docs/manual/html/working-with-cmake.html

<!--- v3.0.0 --->
[gcc-8-issue]: https://gitlab.com/nsnam/ns-3-dev/-/blob/ns-3.36/RELEASE_NOTES.md#release-336
[woss-netcdf-crash]: https://github.com/MetalKnight/woss-ns3/issues/43#event-10588536371
87 changes: 43 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,15 @@ Docker image name: [**`egiona/ns3-woss`**][docker-hub-repo].

| Docker image tag | OS | ns-3 | Build system | WOSS | Dockerfile |
| :---: | :---: | :---: | :---: | :---: | :---: |
| [`u18.04-n3.37-w1.12.4-r2`][image6] | Ubuntu 18.04 | [3.37][ns3.37] | CMake[^ns3-cmake] | [1.12.4][woss-changelog] | [link][file6] |
| [`u18.04-n3.35-w1.12.2-r2`][image5] | Ubuntu 18.04 | [3.35][ns3.35] | Waf | [1.12.2][woss-changelog] | [link][file5] |
| [`u18.04-n3.34-w1.12.2-r2`][image4] | Ubuntu 18.04 | [3.34][ns3.34] | Waf | [1.12.2][woss-changelog] | [link][file4] |
| [`u18.04-n3.34-w1.12.1-r2`][image3] | Ubuntu 18.04 | [3.34][ns3.34] | Waf | [1.12.1][woss-changelog] | [link][file3] |
| [`u18.04-n3.33-w1.12.1-r2`][image2] | Ubuntu 18.04 | [3.33][ns3.33] | Waf | [1.12.1][woss-changelog] | [link][file2] |
| [`u18.04-n3.33-w1.12.0-r2`][image1] | Ubuntu 18.04 | [3.33][ns3.33] | Waf | [1.12.0][woss-changelog] | [link][file1] |
| [`u20.04-n3.40-w1.12.5`][image5] | Ubuntu 20.04 | [3.40][ns3.40] | CMake | [1.12.5][woss-changelog] | [link][file5] |
| [`u20.04-n3.37-w1.12.5`][image4] | Ubuntu 20.04[^gcc-issue] | [3.37][ns3.37] | CMake[^ns3-cmake] | [1.12.5][woss-changelog] | [link][file4] |
| [`u18.04-n3.35-w1.12.5`][image3] | Ubuntu 18.04 | [3.35][ns3.35] | Waf | [1.12.5][woss-changelog] | [link][file3] |
| [`u18.04-n3.34-w1.12.5`][image2] | Ubuntu 18.04 | [3.34][ns3.34] | Waf | [1.12.5][woss-changelog] | [link][file2] |
| [`u18.04-n3.33-w1.12.5`][image1] | Ubuntu 18.04 | [3.33][ns3.33] | Waf | [1.12.5][woss-changelog] | [link][file1] |

Full changelog can be found at [this page](./CHANGELOG.md).

[^gcc-issue]: ns-3.37 images based on Ubuntu 18.04 should NOT be used due an issue related to GCC version mismatch between builds for WOSS requirements and ns-3 itself. More details can be found at [this page](https://gitlab.com/nsnam/ns-3-dev/-/blob/ns-3.36/RELEASE_NOTES.md#release-336).

[^ns3-cmake]: ns-3 adopted the CMake build system starting from 3.36 release. More details can be found at [this page](https://www.nsnam.org/docs/manual/html/working-with-cmake.html).

Expand Down Expand Up @@ -86,25 +89,21 @@ However, _utility scripts_ are only provided for UNIX-like systems.

## Optional instructions

> As long as you `restart` the same container, any modification to its contents will be preserved.
> As long as you `docker restart` the same container, any modification to its contents will be preserved.
However, it is advisable to keep a _local backup copy_ of your modules and experiment results.

1. Execute the utility script to download [WOSS][woss-dbs], [GEBCO 2020][gebco2020], and [GEBCO 2022 2D 15 arc-seconds][gebco2022] databases _locally_ using

`./download-databases.sh <DBs directory>`

_Were this utility to fail (or cannot be run due the lack of a UNIX-like system), download both databases via browser and use your favorite decompression tool on them._
1. Download [WOSS databases][woss-dbs] (_required_), and optional bathymetry databases such as [GEBCO 2020][gebco2020], [GEBCO 2022][gebco2022] or [GEBCO 2023][gebco2023] _locally_.

_More specifically, the extracted_&nbsp; `dbs` _directory should contain 4 sub-directories, namely:_&nbsp; `bathymetry`_,_ `seafloor_sediment`_,_ `ssp`_, and_&nbsp; `transducers`_._

_Once extracted, place the_&nbsp; `GEBCO_XXXX.nc` _file under the_&nbsp; `dbs/bathymetry/` _sub-directory._
More specifically, the extracted `dbs` directory should contain 4 sub-directories, namely: `bathymetry`, `seafloor_sediment`, `ssp`, and `transducers`.

For GEBCO databases users only, place the extracted `GEBCO_XXXX.nc` file under the `dbs/bathymetry/` sub-directory.
It is advisable to store these files outside the container filesystem and using the `docker mount` utility to use them for your simulations.
Please see below step 4.

2. Copy an arbitrary local file into the container's filesystem using

`docker cp <path/to/file> <container ID>:<desired/path/to/file>`

_Be sure to use_&nbsp; `/home/woss_reqs/` _as target container directory to copy the DBs directory into, then adapt ns-3 scripts to point to it._

3. Copy an arbitrary container's file to local filesystem using

`docker cp <container ID>:<path/to/file> <local/path/to/file>`
Expand All @@ -115,13 +114,13 @@ However, it is advisable to keep a _local backup copy_ of your modules and exper

_Local path to be mounted must be absolute. The path within a container's filesystem is placed under its_&nbsp; `/home/` _directory._

_This is only needed the first time a container is instantiated, subsequent calls to_&nbsp; `docker start` _on the same container will automatically load the mounted directory._
_This is only needed the **first time** a container is instantiated, subsequent calls to_&nbsp; `docker start` _on the same container will automatically load the mounted directory._

5. Starting from `r2` images, an environment variables `CXX_CONFIG` is available for user-defined scripts to adapt their GCC compilation parameters; by default, such variable holds the following contents:
5. Starting from `r2` images onwards, an environment variable `CXX_CONFIG` is available for user-defined scripts to adapt their GCC compilation parameters; by default, such variable holds the following contents:

`CXX_CONFIG="-Wall -Werror -Wno-unused-variable"`

Moreover, [build scripts](./u18.04-n3.37-w1.12.4-r2/ns3-build/) have been updated to provide an exit value reflective of ns-3's configuration and build outcome.
Moreover, [build scripts](./u20.04-n3.37-w1.12.4-r2/ns3-build/) have been updated to provide an exit value reflective of ns-3's configuration and build outcome.

# Citing this work

Expand Down Expand Up @@ -161,7 +160,7 @@ chosen for the Docker images does not necessarily apply to them.


[ns3]: https://www.nsnam.org/
[woss]: http://telecom.dei.unipd.it/ns/woss/
[woss]: https://woss.dei.unipd.it/
[docker]: https://www.docker.com/
[woss-ns3]: https://github.com/MetalKnight/woss-ns3

Expand All @@ -171,39 +170,39 @@ chosen for the Docker images does not necessarily apply to them.
[ns3.34]: https://www.nsnam.org/releases/ns-3-34/
[ns3.35]: https://www.nsnam.org/releases/ns-3-35/
[ns3.37]: https://www.nsnam.org/releases/ns-3-37/

[woss-changelog]: http://telecom.dei.unipd.it/ns/woss/doxygen/Changelog.html

[latest-debug]: ./u18.04-n3.37-w1.12.4-r2/ns3-build/build-debug.sh
[latest-optimized]: ./u18.04-n3.37-w1.12.4-r2/ns3-build/build-optimized.sh
[latest-build]: ./u18.04-n3.37-w1.12.4-r2/ns3-build/
[latest-makefile]: ./u18.04-n3.37-w1.12.4-r2/ns3-utils/Makefile

[image6]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.37-w1.12.4-r2
[image5]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.35-w1.12.2-r2
[image4]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.2-r2
[image3]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.1-r2
[image2]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.1-r2
[image1]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.0-r2
[file6]: ./u18.04-n3.37-w1.12.4-r2/Dockerfile
[file5]: ./u18.04-n3.35-w1.12.2-r2/Dockerfile
[file4]: ./u18.04-n3.34-w1.12.2-r2/Dockerfile
[file3]: ./u18.04-n3.34-w1.12.1-r2/Dockerfile
[file2]: ./u18.04-n3.33-w1.12.1-r2/Dockerfile
[file1]: ./u18.04-n3.33-w1.12.0-r2/Dockerfile
[ns3.40]: https://www.nsnam.org/releases/ns-3-40/

[woss-changelog]: https://woss.dei.unipd.it/woss/doxygen/Changelog.html

[latest-debug]: ./u20.04-n3.40-w1.12.5/ns3-build/build-debug.sh
[latest-optimized]: ./u20.04-n3.40-w1.12.5/ns3-build/build-optimized.sh
[latest-build]: ./u20.04-n3.40-w1.12.5/ns3-build/
[latest-makefile]: ./u20.04-n3.40-w1.12.5/ns3-utils/Makefile

[image5]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u20.04-n3.40-w1.12.5
[image4]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u20.04-n3.37-w1.12.5
[image3]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.35-w1.12.5
[image2]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.5
[image1]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.5
[file5]: ./u20.04-n3.40-w1.12.5/Dockerfile
[file4]: ./u20.04-n3.37-w1.12.5/Dockerfile
[file3]: ./u18.04-n3.35-w1.12.5/Dockerfile
[file2]: ./u18.04-n3.34-w1.12.5/Dockerfile
[file1]: ./u18.04-n3.33-w1.12.5/Dockerfile

[docker-install]: https://docs.docker.com/engine/install/

[woss-dbs]: http://telecom.dei.unipd.it/ns/woss/files/WOSS-dbs-v1.6.0.tar.gz
[woss-dbs]: https://woss.dei.unipd.it/woss/files/WOSS-dbs-v1.6.0.tar.gz
[gebco2020]: https://www.bodc.ac.uk/data/open_download/gebco/gebco_2020/zip/
[gebco2022]: https://www.bodc.ac.uk/data/open_download/gebco/gebco_2022/zip/
[gebco2023]: https://www.bodc.ac.uk/data/open_download/gebco/gebco_2023/zip/

[ns3-builds]: https://www.nsnam.org/docs/release/3.37/tutorial/html/getting-started.html#build-profiles
[ns3-builds]: https://www.nsnam.org/docs/release/3.40/tutorial/html/getting-started.html#build-profiles

[cff]: https://citation-file-format.github.io/
[citation]: ./CITATION.cff

[senseslab]: https://senseslab.diag.uniroma1.it/
[docker-license]: ./LICENSE
[ns3-license]: https://www.nsnam.org/develop/contributing-code/licensing/
[woss-license]: http://telecom.dei.unipd.it/ns/woss/doxygen/License.html
[woss-license]: https://woss.dei.unipd.it/woss/doxygen/License.html
115 changes: 0 additions & 115 deletions download-databases.sh
View file

This file was deleted.

Loading

0 comments on commit 0393319

Please sign in to comment.