Development Setup

PDDLSIM uses PDM as its primary build tool and dependency manager. To work on PDDLSIM, it is recommended, but not strictly required you use it, while developing PDDLSIM. PDM-Backend is PDDLSIM's build backend, and PDM is also used to specify development dependencies (via tool.pdm.dev-dependencies), that need to be installed for performing various development related tasks, e.g. running tests with pytest, formatting code with Black, etc.

Note: If you've worked with pyproject.toml based projects before, you might not need to read this. Simply make sure you look at the pyproject.toml file, and install using your tool of choice all of the dependencies you need, including possibly manually installing the development dependencies.

Developing with PDM

To use PDM with the project, first install PDM. See this for more information on installation. Once you have PDM installed run:

pdm use

And select a base interpreter, to configure a Virtual Environment for development. Then, get the command for activating the Virtual Environment with:

pdm venv activate

And run the command.

Note: Just running the command above doesn't activate the Virtual Environment. You must take the text output by the command above, and run that, in your shell, to activate it.

You will now be inside the Virtual Environment, which is currently empty. To install all of PDDLSIM's dependencies, including development-related ones, such that PDDLSIM is in editable mode, run:

pdm install

To avoid installing development dependencies, add the --production flag. Additionally, you can prevent any local package being installed in editable mode by using the --no-editable flag. Other options are by using the --help flag. Installation using pdm install will use the pdm.lock lockfile included in the project source.

At this stage, you should be able to begin development with no issue. Make sure to use the newly created Python interpreter in your code editor. Its path can be found in the .pdm-python file.

Developing without PDM

In this case, you can still use another Python package manager supporting PEP 621 to install the non development dependecies, as Python has still not standardized specifying development dependencies. No matter your alternative Python package manager, you will have to install the development dependencies manually. Additionally, if your Python package manager of choice does not support PEP 621, you will also have to install the regular dependencies manually.

By manual installation, we mean: reading PDDLSIM's pyproject.toml file, going over each dependency specified that is wanted, and installing it, using the corresponding command of your Python package manager.

In the following example, we will use pip, the de-facto standard for Python package management. We assume a sufficient version of pip, with PEP 621 support, is already installed, and do not detail the creation of a Virtual Environment. For creating a Virtual Environment, see this.

Warning: If you continue without creating a Virtual Environment, you will need either root access, for a global install, or will have to use the --user. Either way, pip will install the dependencies globally. This is likely not what you want.

First, we will install the required dependencies, without any development dependencies, in our environment by running:

pip install -e <PATH-TO-PDDLSIM-DIRECTORY>

where <PATH-TO-PDDLSIM-DIRECTORY> should be replaced by the path to the directory containing the PDDLSIM project's source files. Assuming this is the current working directory, one may run:

pip install -e .

Note that the above commands will install PDDLSIM in editable mode. This is generally preferred for development. You can drop the -e flag to install PDDLSIM regularly. Unlike installation with PDM, this will not use the lockfile, as these are also not yet standardized.

After this, assuming you need any development dependencies, to for example, run tests, format code, etc., you will need to install the development dependencies manually. They are found in pyproject.toml, under the [tool.pdm.dev-dependencies] table. See this for information on the format PDM uses to store development dependencies in this table.