Skip to content

Commit

Permalink
ns3-woss: release v4.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
emanuelegiona committed Feb 14, 2024
1 parent 43a0469 commit 35f07e5
Show file tree
Hide file tree
Showing 29 changed files with 2,582 additions and 48 deletions.
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# Changelog

## Release v4.0.0

[Link to release][v400]

Introduced support to new OS and WOSS versions:

- OS: Ubuntu 22.04 LTS

- WOSS: 1.12.6

Moreover, starting from this release images are based on [`egiona/ns3-base`][ns3-base], effectively decoupling the support for new ns-3 versions from WOSS.
This choice aims at providing more granularity for end users, as well as allowing the upgrade of ns-3 version independently from WOSS.

For instance, at the time of the present release, WOSS 1.12.6 cannot be integrated with ns-3 due to the latest changes to the `core` module shipped in ns-3.41.

## Release v3.0.1

[Link to release][v301]
Expand Down Expand Up @@ -92,10 +107,14 @@ Supported versions:
[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
[v301]: https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker/releases/tag/v3.0.1
[v400]: https://github.com/emanuelegiona/ns3-woss-docker/releases/tag/v4.0.0

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

<!--- v3.0.1 --->
[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

<!-- v4.0.0 -->
[ns3-base]: https://github.com/emanuelegiona/ns3-base-docker/
4 changes: 2 additions & 2 deletions CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ authors:
University of Rome
orcid: 'https://orcid.org/0000-0003-0871-7156'
url: >-
https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker
https://github.com/emanuelegiona/ns3-woss-docker
keywords:
- docker
- ns-3
- woss
- network-simulation
license: MIT
doi: 10.5281/zenodo.5727519
doi: 10.5281/zenodo.5727518
86 changes: 43 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,37 @@

[ns-3][ns3] and [WOSS][woss] bundles using [Docker][docker].

The scope of this repository is to automate the installation process of both
ns-3 and WOSS library, in order to provide a hassle-free setup process for a
simulation environment.

Images ship with fully-functioning ns-3 and WOSS library installations, also
including the corresponding [woss-ns3 module][woss-ns3].
ns-3 is provided pre-built in `debug` and `optimized` profiles, with the
*former* being the active version on a first run; utility scripts to quickly
switch between them are provided (see below).
The scope of this repository is to automate the installation process of both ns-3 and WOSS library, in order to provide a hassle-free setup process for a simulation environment.

Images are based on [`egiona/ns3-base`][ns3-base-docker], shipping with WOSS library and the corresponding [woss-ns3 module][woss-ns3] installed.
Please refer to the [`ns3-base`][ns3-base] repository for further details regarding available ns-3 configurations and utilities.

Database configuration is left to the user, mainly for Docker image size
purposes.

## Available configurations *(latest first)*

Docker image name: [**`egiona/ns3-woss`**][docker-hub-repo].

| Docker image tag | OS | ns-3 | Build system | WOSS | Dockerfile |
| :---: | :---: | :---: | :---: | :---: | :---: |
| [`u20.04-n3.40-w1.12.5`][image5] | Ubuntu 20.04 | [3.40][ns3.40] | CMake | [1.12.5][woss-changelog] | [link][file5] |
| [`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] |
| Docker image tag | `egiona/ns3-base` | WOSS | Dockerfile |
| :---: | :---: | :---: | :---: |
| [`u22.04-n3.40-w1.12.6`][img5] | [`u22.04-n3.40`][ns3-base-changelog] | [1.12.6][woss-changelog] | [link][file5] |
| [`u20.04-n3.40-w1.12.6`][img4] | [`u20.04-n3.40`][ns3-base-changelog] | [1.12.6][woss-changelog] | [link][file5] |
| [`u18.04-n3.35-w1.12.6`][img3] | [`u18.04-n3.35`][ns3-base-changelog] | [1.12.6][woss-changelog] | [link][file3] |
| [`u18.04-n3.34-w1.12.6`][img2] | [`u18.04-n3.34`][ns3-base-changelog] | [1.12.6][woss-changelog] | [link][file2] |
| [`u18.04-n3.33-w1.12.6`][img1] | [`u18.04-n3.33`][ns3-base-changelog] | [1.12.6][woss-changelog] | [link][file1] |

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

> New revisions of images (_i.e. `-rN` suffix_) **do not overwrite** previous ones in order to provide backwards compatibility.
Previous tags can still be found on [DockerHub][docker-hub-repo], but their use is discouraged.
_Previous tags are still available on [DockerHub][docker-hub-repo], unless they have been discontinued (see below)._

### Discontinued images

The following image tags have been discontinued and are not available from the DockerHub repository.

If you are using any of these tags, please consider switching to a different one that is still supported.

| Docker image tag | Reason | Date |
| Docker image tag | Motivation | Date |
| :---: | :---: | :---: |
| `u20.04-n3.37-w1.12.5` <br> `u18.04-n3.37-w1.12.4-r2` <br> `u18.04-n3.37-w1.12.4` | GCC compiler issues; <br> not solved by Ubuntu 20.04 upgrade | 2023/10/11 |

Expand All @@ -46,7 +42,7 @@ Any problems should be reported via the GitHub issue tracker.

Users are welcomed to contribute new images (_e.g._ different base image or other ns-3 versions) via Pull Request and adhering to the following style:

- Directory named `<A-B-C>` with: `A` equal to an arbitrary versioned base image short-hand (_i.e._ `u20.04` refers to Ubuntu 20.04); `B` equal to the ns-3 version bundled (_i.e._ `n3.40` refers to ns-3.40); and `C` equal to the WOSS version bundled (_i.e._ `w1.12.5` refers to WOSS 1.12.5).
- Directory named `<A-B>` with: `A` equal to an arbitrary versioned base image short-hand (_i.e._ `u22.04-n3.40` refers to the same `egiona/ns3-base` tag); and `B` equal to the WOSS version bundled (_i.e._ `w1.12.6` refers to WOSS 1.12.6).

Such directory name will also be used as image tag.

Expand Down Expand Up @@ -103,6 +99,7 @@ However, _utility scripts_ are only provided for UNIX-like systems.

This script allows for easy decoupling of development directory from ns-3's source directory.
Indeed, it is possible to keep novel modules and program driver scripts outside `src` (or `contrib`) and `scratch` directories of the ns-3 installation directory during development, and only copying them afterwards.
This is especially useful when paired with mounted directories.

Multiple targets are present, allowing: ns-3 current version checking, compilation and execution of simulation driver programs (copying them to `scratch` subdir first), management of ns-3 modules (creation in `contrib` subdir and copy outside, synchronization of contents, elimination), and debugging (GNU debugger, Valgrind, ns-3 tests).

Expand Down Expand Up @@ -133,43 +130,45 @@ However, it is advisable to keep a _local backup copy_ of your modules and exper

4. Mount a local directory into a container (just once, instead of `docker run`) using

`./mount.sh <local/path/to/directory> <path/to/directory> <container name> <image name>`
`docker run -td --mount type=bind,source=<local/FS/path>,target=<container/FS/path> --name <container name> <image ID>`

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

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

_**Warning:** existing container contents at the same target path will be overwritten with the ones provided by the local filesystem._

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](./u20.04-n3.40-w1.12.5/ns3-build/) have been updated to provide an exit value reflective of ns-3's configuration and build outcome.
Moreover, [build scripts][latest-build] have been updated to provide an exit value reflective of ns-3's configuration and build outcome.

# Citing this work

If you use any of the Docker images described in this repository, please cite this work using any of the following methods:

**APA**
```
Giona, E. ns-3 and WOSS Docker images [Computer software]. https://doi.org/10.5281/zenodo.5727519
Giona, E. ns-3 and WOSS Docker images [Computer software]. https://doi.org/10.5281/zenodo.5727518
```

**BibTeX**
```
@software{Giona_ns-3_and_WOSS,
author = {Giona, Emanuele},
doi = {10.5281/zenodo.5727519},
doi = {10.5281/zenodo.5727518},
license = {MIT},
title = {{ns-3 and WOSS Docker images}},
url = {https://github.com/SENSES-Lab-Sapienza/ns3-woss-docker}
url = {https://github.com/emanuelegiona/ns3-woss-docker}
}
```

Bibliography entries generated using [Citation File Format][cff] described in the [CITATION.cff][citation] file.

# License

**Copyright (c) 2023 Emanuele Giona ([SENSES Lab][senseslab], Sapienza University of Rome)**
**Copyright (c) 2024 Emanuele Giona ([SENSES Lab][senseslab], Sapienza University of Rome)**

This repository and Docker images themselves are distributed under [MIT license][docker-license].

Expand All @@ -188,27 +187,28 @@ chosen for the Docker images does not necessarily apply to them.
[woss-ns3]: https://github.com/MetalKnight/woss-ns3

[docker-hub-repo]: https://hub.docker.com/r/egiona/ns3-woss
[ns3-base-docker]: https://hub.docker.com/r/egiona/ns3-base

[ns3.33]: https://www.nsnam.org/releases/ns-3-33/
[ns3.34]: https://www.nsnam.org/releases/ns-3-34/
[ns3.35]: https://www.nsnam.org/releases/ns-3-35/
[ns3.40]: https://www.nsnam.org/releases/ns-3-40/
[ns3-base]: https://github.com/emanuelegiona/ns3-base-docker
[ns3-base-changelog]: https://github.com/emanuelegiona/ns3-base-docker/blob/main/CHANGELOG.md

[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
[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
[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
[latest-debug]: ./u22.04-n3.40-w1.12.6/ns3-build/build-debug.sh
[latest-optimized]: ./u22.04-n3.40-w1.12.6/ns3-build/build-optimized.sh
[latest-build]: ./u22.04-n3.40-w1.12.6/ns3-build/
[latest-makefile]: ./u22.04-n3.40-w1.12.6/ns3-utils/Makefile

[img5]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u22.04-n3.40-w1.12.6
[img4]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u20.04-n3.40-w1.12.6
[img3]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.35-w1.12.6
[img2]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.34-w1.12.6
[img1]: https://hub.docker.com/r/egiona/ns3-woss/tags?page=1&name=u18.04-n3.33-w1.12.6
[file5]: ./u22.04-n3.40-w1.12.6/Dockerfile
[file4]: ./u20.04-n3.40-w1.12.6/Dockerfile
[file3]: ./u18.04-n3.35-w1.12.6/Dockerfile
[file2]: ./u18.04-n3.34-w1.12.6/Dockerfile
[file1]: ./u18.04-n3.33-w1.12.6/Dockerfile

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

Expand Down
16 changes: 13 additions & 3 deletions mount.sh → build-all.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# MIT License

# Copyright (c) 2021 Emanuele Giona <[email protected]> (SENSES Lab,
# Copyright (c) 2024 Emanuele Giona <[email protected]> (SENSES Lab,
# Sapienza University of Rome)

# Permission is hereby granted, free of charge, to any person obtaining a copy
Expand All @@ -23,6 +23,16 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

docker run -t -d --mount type=bind,source=$1,target=/home/$2 --name $3 $4
IMG_NAME=egiona/ns3-woss

exit 0
# Iterate on all supported configurations and (re)build images
for img_dir in */ ; do
CURR_TAG="${img_dir%/}"

echo ">>> Building image '${IMG_NAME}:${CURR_TAG}'..."
cd "${CURR_TAG}" && \
docker buildx build -t "${IMG_NAME}:${CURR_TAG}" . && \
docker push "${IMG_NAME}:${CURR_TAG}" && \
docker image rm "${IMG_NAME}:${CURR_TAG}" && \
cd ..
done
109 changes: 109 additions & 0 deletions u18.04-n3.33-w1.12.6/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# syntax=docker/dockerfile:1

# MIT License

# Copyright (c) 2024 Emanuele Giona <[email protected]> (SENSES Lab,
# Sapienza University of Rome)

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

FROM egiona/ns3-base:u18.04-n3.33

LABEL maintainer="[email protected]"
LABEL version="0.1"
LABEL description="ns3-base:u18.04-n3.33 and WOSS 1.12.6"

ARG WOSS_VER="1.12.6"
ARG TMP_DOWNLOAD_DIR="/home/downloads"
ARG WOSS_LIB_BASE="/home/woss"

# ===== Evinronment variables available in containers too =====
# ns3-base provides the following environment variables already:
# - NS3_DEBUG_DIR: installation directory for ns-3 in 'debug' profile
# - NS3_OPTIMIZED_DIR: installation directory for ns-3 in 'optimized' profile
# - NS3_PY_ENV: ns-3 dedicated Python 3 environment

# WOSS-related variables
ENV WOSS_LIB_SRC="$WOSS_LIB_BASE/WOSS-$WOSS_VER"
ENV WOSS_LIB_DIR="/home/woss_lib"
ENV WOSS_REQS_DIR="/home/woss_reqs"

# ===== Basic OS updates and ns-3 requirements =====
ARG DEBIAN_FRONTEND=noninteractive
RUN apt -y update && apt -y upgrade && \
# ===== Downloading: WOSS requirements and library =====
cd /home && mkdir "$TMP_DOWNLOAD_DIR" && cd "$TMP_DOWNLOAD_DIR" && \
# WOSS requirements
mkdir "$WOSS_LIB_BASE" && mkdir "$WOSS_REQS_DIR" && cd "$TMP_DOWNLOAD_DIR" && \
wget http://oalib.hlsresearch.com/AcousticsToolbox/at_2023_5_18.zip && \
unzip at_2023_5_18.zip && rm at/Makefile && mv at "$WOSS_REQS_DIR/" && \
wget https://github.com/HDFGroup/hdf5/archive/refs/tags/hdf5-1_14_2.tar.gz && \
tar -xf hdf5-1_14_2.tar.gz && \
wget https://downloads.unidata.ucar.edu/netcdf-c/4.9.2/netcdf-c-4.9.2.tar.gz && \
tar -xf netcdf-c-4.9.2.tar.gz && \
wget https://downloads.unidata.ucar.edu/netcdf-cxx/4.3.1/netcdf-cxx4-4.3.1.tar.gz && \
tar -xf netcdf-cxx4-4.3.1.tar.gz && \
# WOSS library source and ns-3 module
wget "https://github.com/signetlabdei/WOSS/archive/refs/tags/$WOSS_VER.tar.gz" && \
tar -xf "$WOSS_VER.tar.gz" && mv "WOSS-$WOSS_VER" "$WOSS_LIB_BASE" && \
wget "https://github.com/MetalKnight/woss-ns3/archive/refs/tags/v$WOSS_VER.tar.gz" && \
tar -xf "v$WOSS_VER.tar.gz" && mv "woss-ns3-$WOSS_VER" "$WOSS_LIB_BASE"

# ===== Installing: WOSS requirements and WOSS library =====
COPY at/Makefile "$WOSS_REQS_DIR/at/"
RUN cd "$WOSS_REQS_DIR/at" && \
make clean && make && \
echo "export PATH=$PATH:$WOSS_REQS_DIR/at/Bellhop/" >> ~/.bashrc && \
# HDF5
cd "$TMP_DOWNLOAD_DIR" && cd hdf5-hdf5-1_14_2 && \
./configure --enable-shared --prefix="$WOSS_REQS_DIR" && \
make && make install && \
# NetCDF-C
cd ../netcdf-c-4.9.2 && \
./configure --prefix="$WOSS_REQS_DIR" --enable-netcdf-4 --enable-shared --disable-dap --disable-byterange CPPFLAGS="$CPPFLAGS -I$WOSS_REQS_DIR/include" LDFLAGS="$LDFLAGS -L$WOSS_REQS_DIR/lib" && \
make && make install && \
# NetCDF-C++
cd ../netcdf-cxx4-4.3.1 && \
./configure --prefix="$WOSS_REQS_DIR" --enable-shared CPPFLAGS="$CPPFLAGS -I$WOSS_REQS_DIR/include" LDFLAGS="$LDFLAGS -L$WOSS_REQS_DIR/lib" && \
make && make install && \
# WOSS library
mkdir "$WOSS_LIB_DIR" && cd "$WOSS_LIB_SRC" && \
./autogen.sh && ./configure --with-netcdf4="$WOSS_REQS_DIR" --with-pthread --prefix="$WOSS_LIB_DIR" && \
make && make install

# ===== Building: ns-3 with WOSS; Cleanup: temporary downloads directory =====
ENV WOSS_LIB_DIR="/home/woss_lib/lib"
ENV CXX_CONFIG="-Wall -Werror -Wno-unused-variable"

COPY ns3-build/* ns3-utils/* /home/
RUN cd /home && \
# Build: debug
cp -R "$WOSS_LIB_BASE/woss-ns3-$WOSS_VER/" "$NS3_DEBUG_DIR/src/" && \
mv "$NS3_DEBUG_DIR/src/woss-ns3-$WOSS_VER" "$NS3_DEBUG_DIR/src/woss-ns3" && \
chmod +x build-debug.sh && ./build-debug.sh && \
# Build: optimized
cp -R "$WOSS_LIB_BASE/woss-ns3-$WOSS_VER/" "$NS3_OPTIMIZED_DIR/src/" && \
mv "$NS3_OPTIMIZED_DIR/src/woss-ns3-$WOSS_VER" "$NS3_OPTIMIZED_DIR/src/woss-ns3" && \
chmod +x build-optimized.sh && ./build-optimized.sh && \
# Utility for switching between profiles
# [ ns3-base already provides the .bashrc signal trap ]
# Cleanup
rm -rf "$TMP_DOWNLOAD_DIR" && ./build-debug.sh

CMD ["/bin/bash"]
Loading

0 comments on commit 35f07e5

Please sign in to comment.