# opp_env: Automated Installation of OMNeT++ Simulation Frameworks
`opp_env` is a powerful tool that allows for the easy and automated installation
of OMNeT++ simulation frameworks and models, including dependencies like INET
Framework and OMNeT++ itself. It can install any version of OMNeT++ and INET, as
well as currently selected versions of Veins, SimuLTE, Simu5G and other models.
We are working towards expanding its database with more models, and we are open
to suggestions and contributions.
`opp_env` supports Linux and macOS systems. On Windows 10 & 11, `opp_env` can be
run on the Windows Subsystem for Linux (WSL2).
> [!NOTE]
> `opp_env` relies on [Nix](https://nixos.org/), a powerful package manager that
> provides isolation between different versions of dependencies and allows for
> reproducible builds. By leveraging the power of Nix, `opp_env` ensures that each
> installation is consistent and can be easily replicated on different machines.
## Features
`opp_env` provides a number of powerful features that make it a valuable tool for
any researcher or developer working with OMNeT++ simulation frameworks:
- Automated installation of OMNeT++ simulation frameworks and models, including
dependencies like INET Framework and OMNeT++ itself.
- Support for any version of OMNeT++ and INET, as well as select
versions of Veins, SimuLTE, Simu5G and other 3rd party models.
- Reproducible builds thanks to the powerful isolation provided by Nix.
- Easy to use shell command that sets up an environment for working with the
selected simulation framework.
- Customizable configuration options that allow for advanced control over the
installation process.
## Usage
Using `opp_env` is simple. To install a specific version of a simulation framework
and its dependencies, first create a workspace and initialize it:
mkdir workspace && cd workspace && opp_env init
Then run the following command:
opp_env install <framework-version>
For example, to install Simu5G version 1.2.1, run the following command:
opp_env install simu5g-1.2.1
This will download Simu5G, the matching INET and OMNeT++ packages and compile
them.
> [!TIP]
> To install the latest version of a package, use the `latest` pseudo-version
> e.g. to install the latest version of OMNeT++ use `opp_env install omnetpp-latest`
To open a shell prompt where you can use the recently installed Simu5G model, type:
opp_env shell simu5g-1.2.1
> [!IMPORTANT]
> You cannot use the packages you installed via `opp_env` outside of `opp_env shell` or `opp_env run`.
> [!TIP]
> To see the list of available packages, type: `opp_env list`.
> [Scroll down](#supported-simulation-frameworks) for the output from a recently released version.
## Installation
### Installing opp_env on Linux and macOS
`opp_env` requires Python3, pip and Nix installed on your machine. Everything else will be installed by Nix.
#### Installing Python3 and pip
Use your operating system's package manager to install Python3 and pip.
#### Installing Nix
You can download and install Nix from [here](https://nixos.org/download). All other
`opp_env` dependencies are automatically installed using the Nix package manager.
> [!NOTE]
> For macOS users, it is recommended to add
> ```
> if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
> . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
> fi
> ```
> to your `~/.zshrc` or `~/.bashrc` file after a successful Nix installation.
> The Nix installer adds these lines to your global `/etc/bashrc` and `/etc/zshrc`
> files, but macOS system upgrades regularly overwrite these system files rendering
> the Nix installation unavailable.
#### Installing opp_env with pip
Once you have the prerequisites, you can install `opp_env` using `pip`:
First, make sure that `pip` is the latest version:
pip install --upgrade pip
You can now install `opp_env`:
pip3 install opp-env
> [!IMPORTANT]
> On some system, namely recent versions of Ubuntu / Debian, this
> command stops with an error message: `error: externally-managed-environment`
>
> To work around the error, follow the instructions in the printed message, which
> boils down to either adding the `--break-system-packages` option to the
> `pip install` commands, or setting up a Python virtual environment
> ([venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/))
> and working from there.
When you install `opp_env` using pip, it installs the `opp_env` Python module,
as well as a small script into your system's path (e.g. `~/.local/bin` or the
virtual environment's bin directory) that allows you to invoke it from the shell.
The `opp_env` command is equivalent to running `python -m opp_env`, which also
runs the `opp_env` Python module. (Make sure that `~/.local/bin` is in
your `PATH` environment variable. Acivating the python virtual environment
does this for you automatically.)
### Installing opp_env on Windows 10 & 11 (with WSL2)
`opp_env` requires the Nix package manager which is available only on Linux and macOS,
but you can still use `opp_env` on Windows running it in a WSL2 (Windows Subsystem
for Linux) container.
For Windows 10 and 11, we provide a pre-packaged, Ubuntu 22.04 based WSL2
container with all the necessary dependencies (Python3, pip, Nix, etc.) already installed.
To install the `opp_env` WSL distro image, open a command prompt and run the
following command:
curl.exe -L https://github.com/omnetpp/opp_env/releases/download/wsl/opp_env-wsl.tar.gz | wsl --import opp_env .\opp_env-wsl -
The above command will download and install a WSL2 container image for `opp_env` and
place it into the `opp_env-wsl` folder. The shell can be started with:
wsl -d opp_env --cd ~
Once you are inside the container, you can run the `opp_env` command as
suggested in the previous section.
### Installing opp_env with Docker
We provide docker images for `opp_env` that can be installed with the following
command:
docker pull ghcr.io/omnetpp/opp_env
You can try it interactively with:
docker run -it ghcr.io/omnetpp/opp_env
This image is the same as the one used for generating the WSL2 image.
## Developing or changing opp_env
If you want to contribute to the development of `opp_env` or need to modify the
source code for any reason, you can install the package in editable mode by
cloning the git repo, changing to its root directory and using
the following command:
pip install --editable .
This will install the Python module and the `opp_env` command, but with the
added ability to make local modifications that will take effect immediately.
If you get the `error: externally-managed-environment` message, see the note
marked IMPORTANT above.
In case of other errors, try upgrading pip to the latest version first by
running `python3 -m pip install --upgrade pip`.
### Building the Python Package
To build the Python package, you first need to install the `build` package by
running the following command:
pip install --upgrade build
Once you have `build` installed, you can build the package by running:
python3 -m build
If you have any issues or questions, feel free to open an issue on the GitHub
repository. We are always happy to help!
Raw data
{
"_id": null,
"home_page": null,
"name": "opp-env",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Rudolf Hornig <rudi@omnetpp.org>",
"keywords": "omnetpp, omnest, simulation, discrete, event, package manager, model",
"author": null,
"author_email": "Andr\u00e1s Varga <andras@omnetpp.org>, Levente M\u00e9sz\u00e1ros <levy@omnetpp.org>, Rudolf Hornig <rudi@omnetpp.org>",
"download_url": "https://files.pythonhosted.org/packages/79/15/66a78f883b45cd9b2f95e8e27ed04461fd1dacb136edcb6bc682ee2daf3e/opp_env-0.29.1.240516.tar.gz",
"platform": null,
"description": "# opp_env: Automated Installation of OMNeT++ Simulation Frameworks\n\n`opp_env` is a powerful tool that allows for the easy and automated installation\nof OMNeT++ simulation frameworks and models, including dependencies like INET\nFramework and OMNeT++ itself. It can install any version of OMNeT++ and INET, as\nwell as currently selected versions of Veins, SimuLTE, Simu5G and other models.\nWe are working towards expanding its database with more models, and we are open\nto suggestions and contributions.\n\n`opp_env` supports Linux and macOS systems. On Windows 10 & 11, `opp_env` can be \nrun on the Windows Subsystem for Linux (WSL2).\n\n> [!NOTE]\n> `opp_env` relies on [Nix](https://nixos.org/), a powerful package manager that\n> provides isolation between different versions of dependencies and allows for\n> reproducible builds. By leveraging the power of Nix, `opp_env` ensures that each\n> installation is consistent and can be easily replicated on different machines.\n\n## Features\n\n`opp_env` provides a number of powerful features that make it a valuable tool for\nany researcher or developer working with OMNeT++ simulation frameworks:\n\n- Automated installation of OMNeT++ simulation frameworks and models, including\n dependencies like INET Framework and OMNeT++ itself.\n- Support for any version of OMNeT++ and INET, as well as select\n versions of Veins, SimuLTE, Simu5G and other 3rd party models.\n- Reproducible builds thanks to the powerful isolation provided by Nix.\n- Easy to use shell command that sets up an environment for working with the\n selected simulation framework.\n- Customizable configuration options that allow for advanced control over the\n installation process.\n\n## Usage\n\nUsing `opp_env` is simple. To install a specific version of a simulation framework\nand its dependencies, first create a workspace and initialize it:\n\n mkdir workspace && cd workspace && opp_env init\n\nThen run the following command:\n\n opp_env install <framework-version>\n\nFor example, to install Simu5G version 1.2.1, run the following command:\n\n opp_env install simu5g-1.2.1\n\nThis will download Simu5G, the matching INET and OMNeT++ packages and compile\nthem.\n\n> [!TIP]\n> To install the latest version of a package, use the `latest` pseudo-version\n> e.g. to install the latest version of OMNeT++ use `opp_env install omnetpp-latest`\n\nTo open a shell prompt where you can use the recently installed Simu5G model, type:\n\n opp_env shell simu5g-1.2.1\n\n> [!IMPORTANT]\n> You cannot use the packages you installed via `opp_env` outside of `opp_env shell` or `opp_env run`. \n\n> [!TIP]\n> To see the list of available packages, type: `opp_env list`.\n> [Scroll down](#supported-simulation-frameworks) for the output from a recently released version.\n\n## Installation\n\n### Installing opp_env on Linux and macOS\n\n`opp_env` requires Python3, pip and Nix installed on your machine. Everything else will be installed by Nix. \n\n#### Installing Python3 and pip\n\nUse your operating system's package manager to install Python3 and pip.\n\n#### Installing Nix\n\nYou can download and install Nix from [here](https://nixos.org/download). All other\n`opp_env` dependencies are automatically installed using the Nix package manager.\n\n> [!NOTE] \n> For macOS users, it is recommended to add \n> ```\n> if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then\n> . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'\n> fi\n> ```\n> to your `~/.zshrc` or `~/.bashrc` file after a successful Nix installation. \n> The Nix installer adds these lines to your global `/etc/bashrc` and `/etc/zshrc`\n> files, but macOS system upgrades regularly overwrite these system files rendering\n> the Nix installation unavailable.\n\n#### Installing opp_env with pip\n\nOnce you have the prerequisites, you can install `opp_env` using `pip`:\n\nFirst, make sure that `pip` is the latest version:\n\n pip install --upgrade pip\n\nYou can now install `opp_env`:\n\n pip3 install opp-env\n\n> [!IMPORTANT]\n> On some system, namely recent versions of Ubuntu / Debian, this\n> command stops with an error message: `error: externally-managed-environment`\n>\n> To work around the error, follow the instructions in the printed message, which\n> boils down to either adding the `--break-system-packages` option to the\n> `pip install` commands, or setting up a Python virtual environment\n> ([venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/))\n> and working from there.\n\nWhen you install `opp_env` using pip, it installs the `opp_env` Python module,\nas well as a small script into your system's path (e.g. `~/.local/bin` or the\nvirtual environment's bin directory) that allows you to invoke it from the shell.\nThe `opp_env` command is equivalent to running `python -m opp_env`, which also\nruns the `opp_env` Python module. (Make sure that `~/.local/bin` is in\nyour `PATH` environment variable. Acivating the python virtual environment \ndoes this for you automatically.)\n\n### Installing opp_env on Windows 10 & 11 (with WSL2)\n\n`opp_env` requires the Nix package manager which is available only on Linux and macOS,\nbut you can still use `opp_env` on Windows running it in a WSL2 (Windows Subsystem \nfor Linux) container.\n\nFor Windows 10 and 11, we provide a pre-packaged, Ubuntu 22.04 based WSL2\ncontainer with all the necessary dependencies (Python3, pip, Nix, etc.) already installed.\n\nTo install the `opp_env` WSL distro image, open a command prompt and run the\nfollowing command:\n\n curl.exe -L https://github.com/omnetpp/opp_env/releases/download/wsl/opp_env-wsl.tar.gz | wsl --import opp_env .\\opp_env-wsl -\n\nThe above command will download and install a WSL2 container image for `opp_env` and\nplace it into the `opp_env-wsl` folder. The shell can be started with:\n\n wsl -d opp_env --cd ~\n\nOnce you are inside the container, you can run the `opp_env` command as\nsuggested in the previous section.\n\n### Installing opp_env with Docker\n\nWe provide docker images for `opp_env` that can be installed with the following\ncommand:\n\n docker pull ghcr.io/omnetpp/opp_env\n\nYou can try it interactively with:\n\n docker run -it ghcr.io/omnetpp/opp_env\n\nThis image is the same as the one used for generating the WSL2 image.\n\n## Developing or changing opp_env\n\nIf you want to contribute to the development of `opp_env` or need to modify the\nsource code for any reason, you can install the package in editable mode by\ncloning the git repo, changing to its root directory and using\nthe following command:\n\n pip install --editable .\n\nThis will install the Python module and the `opp_env` command, but with the\nadded ability to make local modifications that will take effect immediately.\n\nIf you get the `error: externally-managed-environment` message, see the note\nmarked IMPORTANT above.\n\nIn case of other errors, try upgrading pip to the latest version first by\nrunning `python3 -m pip install --upgrade pip`.\n\n### Building the Python Package\n\nTo build the Python package, you first need to install the `build` package by\nrunning the following command:\n\n pip install --upgrade build\n\nOnce you have `build` installed, you can build the package by running:\n\n python3 -m build\n\nIf you have any issues or questions, feel free to open an issue on the GitHub\nrepository. We are always happy to help!\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool, that sets up the development environment for OMNeT++ projects",
"version": "0.29.1.240516",
"project_urls": {
"Changelog": "https://github.com/omnetpp/opp_env/commits/main",
"Changes": "https://github.com/omnetpp/opp_env/blob/main/CHANGES.md",
"Documentation": "https://github.com/omnetpp/opp_env/blob/main/README.md",
"Homepage": "https://omnetpp.org",
"Issues": "https://github.com/omnetpp/opp_env/issues",
"Repository": "https://github.com/omnetpp/opp_env"
},
"split_keywords": [
"omnetpp",
" omnest",
" simulation",
" discrete",
" event",
" package manager",
" model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42b4cda05c7a1f581f72e3dd618e15447d63c3c29522e20d50bb203305ac08df",
"md5": "1fa8558c64126af37f0899dc8caed486",
"sha256": "db0a8031481dd0857d0fcec48eabe0bf94b807748a4f3fed88b0baa6b253b2f6"
},
"downloads": -1,
"filename": "opp_env-0.29.1.240516-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fa8558c64126af37f0899dc8caed486",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 74639,
"upload_time": "2024-05-16T11:46:39",
"upload_time_iso_8601": "2024-05-16T11:46:39.429726Z",
"url": "https://files.pythonhosted.org/packages/42/b4/cda05c7a1f581f72e3dd618e15447d63c3c29522e20d50bb203305ac08df/opp_env-0.29.1.240516-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "791566a78f883b45cd9b2f95e8e27ed04461fd1dacb136edcb6bc682ee2daf3e",
"md5": "c1536f843d280cbaf2ba67772f02cba1",
"sha256": "818cc9b7e4ed4133c89442df0c607313f96298c471b763691f4721c27489b4a3"
},
"downloads": -1,
"filename": "opp_env-0.29.1.240516.tar.gz",
"has_sig": false,
"md5_digest": "c1536f843d280cbaf2ba67772f02cba1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 82699,
"upload_time": "2024-05-16T11:46:41",
"upload_time_iso_8601": "2024-05-16T11:46:41.226525Z",
"url": "https://files.pythonhosted.org/packages/79/15/66a78f883b45cd9b2f95e8e27ed04461fd1dacb136edcb6bc682ee2daf3e/opp_env-0.29.1.240516.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-16 11:46:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "omnetpp",
"github_project": "opp_env",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "opp-env"
}
JSON
