diff options
Diffstat (limited to 'DEVELOPING.md')
| -rw-r--r-- | DEVELOPING.md | 46 |
1 files changed, 21 insertions, 25 deletions
diff --git a/DEVELOPING.md b/DEVELOPING.md index 934369c..4e47b84 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -22,33 +22,27 @@ pipenv run lint ## Running snekbox -The Docker image can be built with: - -``` -pipenv run build -``` - -Use Docker Compose to start snekbox: +Use Docker Compose to start snekbox in development mode. The optional `--build` argument can be passed to force the image to be rebuilt. ``` docker-compose up ``` -## Running Tests +The container has all development dependencies. The repository on the host is mounted within the container; changes made to local files will also affect the container. + +Note that the compose file depends on the environment variable `PWD` being set to the current working directory. It needs it to create the aforementioned bind mount. Unix shells normally have this set already. If for some reason it is not set, it needs to be manually set. A convenient way to set it is to define it in a `.env` file which Docker Compose will automatically read. -Tests are run through coverage.py using unittest. Before tests can run, the dev venv Docker image has to be built: +To build a normal container that can be used in production, run ``` -pipenv run builddev +pipenv run build ``` -Alternatively, the following command will build the image and then run the tests: +Refer to the [README] for how to run the container normally. -``` -pipenv run testb -``` +## Running Tests -If the image doesn't need to be built, the tests can be run with: +Tests are run through coverage.py using unittest. To run the tests within a development container, run ``` pipenv run test @@ -62,7 +56,7 @@ To see a coverage report, run pipenv run report ``` -Alternatively, a report can be generated as HTML: +Alternatively, a report can be generated as HTML with ``` pipenv run coverage html @@ -70,20 +64,21 @@ pipenv run coverage html The HTML will output to `./htmlcov/` by default +## Launching a Shell in the Container -## The `devsh` Helper Script - -This script starts a `bash` shell inside the venv Docker container and attaches to it. Unlike the production image, the venv image that is built by this script contains dev dependencies too. The project directory is mounted inside the container so any filesystem changes made inside the container affect the actual local project. - -### Usage +A bash shell can be launched in the development container using ``` -pipenv run devsh [--build [--clean]] [bash_args ...] +pipenv run devsh ``` -* `--build` Build the venv Docker image -* `--clean` Clean up dangling Docker images (only works if `--build` precedes it) -* `bash_args` Arguments to pass to `/bin/bash` (for example `-c "echo hello"`). An interactive shell is launched if no arguments are given +This creates a new container which will get deleted once the shell session ends. + +It's possible to run a command directly; it supports the same arguments that `bash` supports. + +```bash +pipenv run devsh -c 'echo hello' +``` ### Invoking NsJail @@ -96,3 +91,4 @@ python -m snekbox 'print("hello world!")' --time_limit 0 With this command, NsJail uses the same configuration normally used through the web API. It also has an alias, `pipenv run eval`. [pipenv]: https://docs.pipenv.org/en/latest/ +[readme]: README.md |