Metadata-Version: 2.1
Name: drekar-launch
Version: 0.1.2
Summary: A simple launcher for Robotics applications
Author-email: John Wason <wason@wasontech.com>
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pyyaml
Requires-Dist: appdirs
Requires-Dist: drekar-launch-process
Requires-Dist: jinja2
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pywin32 ; (platform_system == "Windows") and extra == 'test'

# Drekar Launch

`drekar-launch` is a simple tool to launch and manage multiple processes. It is based on the process management code
extracted from the `pyri-core` module, part of the PyRI Open-Source Teach Pendant

`drekar-launch` has a similar goal to `roslaunch`, but
designed to be simpler and independent of ROS. It also has improvements in handling Windows process management
using Windows Job Objects. Yaml files are used to configure the processes to launch.

`drekar-launch` will show a minimal GUI windows when the `--gui` is specified. This window shows same basic
information, and has a "Stop All" button that will shut down all tasks. This GUI is useful if `drekar-launch` is 
started interactively by the user rather than running as a background service.

See also `drekar-launch-process`, a companion library that contains utility functions to use within processes
hosted by `drekar-launch`. The functions `wait_exit()` and `wait_exit_callback()` assist in receiving shutdown
signals in a reliable cross-platform manner.

See `drekar-launch-process`: https://github.com/johnwason/drekar-launch-process

## Installation

```
python -m pip install --user drekar-launch
```

On Ubuntu, it may be necessary to replace `python` with `python3`.

## Usage

Yaml files are used to configure the processes to launch. The following is an example of a `drekar-launch.yaml` 
file that launches two Python servers.

```yaml
name: example_http_servers
tasks:
  - name: http_server_1
    program: python.exe
    args: example_http_server.py 8100 Server1
    cwd: .
  - name: http_server_2
    program: python.exe
    args:
      - example_http_server.py
      - 8101
      - Hello from Server2!
    start-delay: 1
```

The `example_http_server.py` program uses `drekar-launch-process` to wait for the shutdown signal.

In this example, the `name` field is the name of the launch group. The `tasks` section contains a list of tasks to 
launch. The following fields are used to configure the launch of each task:

* `name`: The name of the process
* `program`: The program to execute
* `args`: The command line arguments to pass to `program`
* `cwd` (optional): The working directory to run the program. Defaults to current directory.
* `start-delay` (optional): Delay the start of the program by specified seconds
* `restart` (optional): If true, process will be restarted if it exits
* `restart-backoff` (optional): Delay in seconds before restarting after exit
* `quit-on-terminate` (optional): If `true`, all processes will exit if the process exits
* `tags` (optional): Unused
* `environment` (optional): Key/value pairs to add to environment
* `env-file` (optional): File of environmental variable to override the environment

`drekar-launch` by default will load `drekar-launch.yaml` in the current directory. To run with default settings,
simply call `drekar-launch`.

```
drekar-launch
```

In some cases, it may be necessary to use `python` to launch. The `drekar-launch` executable may not be installed
to `PATH`.

```
python -m drekar_launch
```

`drekar-launch` accepts the following optional command line arguments:

* `--config=`: Specify an alternative configuration file
* `--config-js=`: Specify an alternative configuration file that uses Jinja2 templates
* `--cwd=`: Set the default working directory for processes
* `--name=`: Override the name of the launch group
* `--quiet`: Flag to suppress outputting to the terminal
* `--gui`: Show a simple GUI to stop the tasks

Drekar Launch saves the output to log files located in the following locations:

* Windows: `%LOCALAPPDATA%\drekar-launch\drekar-launch\Logs`
* Linux: `$HOME/.cache/SuperApp/log`
* Mac OS: `$HOME//Library/Logs/drekar-launch`

Logs should be periodically cleaned if too much disk space is used.

*TODO: Add automatic log cleaning.*

Jinja2 Templates can be used to generate configurations that fill in values at runtime or even include other
templates. See the Jinja2 documentation (https://jinja.palletsprojects.com/) for more information on using templates.

Four variables are available in the template:

* `configpath`: Absolute path to the configuration file
* `configdir`: Directory containing the configuration file
* `env`: Environmental variables
* `platform`: Current platform of the system as returned by `sys.platform`. Typically `win32`, `linux`, or `darwin` (Mac OS)
* `vars`: Extra variables passed on the command line. Use `--var-name=value`, where `name` and `value` are replaced with specific values.

For example, if `CONDA_PREFIX` needs to be used:

```yaml
name: example_http_servers
tasks:
  - name: http_server_1
    program: {{ env["CONDA_PREFIX"] }}/python.exe
    args: {{ configdir }}/example_http_server.py 8100 Server1
    cwd: {{ env["CONDA_PREFIX"] }}
```


## License

Apache 2.0
