README.md-template

`pugs`'s plugin `_PLUGIN_NAME_`
===============================

# Building `_PLUGIN_NAME_`

## `pugs` installation

Building this plugin requires an **installed** version of `pugs`.
`pugs` follows standard `cmake` installation recipes.

Before building `pugs` one should define its installation directory.
In the `pugs` compilation directory one should execute
```shell
cmake -DCMAKE_INSTALL_PREFIX=[pugs_install_dir] [pugs_src_path] [...]
```
where `[pugs_install_dir]` is the chosen installation directory.

Then one simply runs
```shell
make install
```

## building the plugin `_PLUGIN_NAME_`

> **Warning**:<br>
> Building `_PLUGIN_NAME_` in its source directory is
> **forbidden**. Trying to do so will result in a failure. However it
> generally leaves some garbage files in the source directory, namely
> the `CMakeCache.txt` and the `CMakeFiles` directory. `CMake` itself
> is not able to remove them, to avoid the risk of compilation issues,
> one has to dot it manually...

In the plugin build directory one runs
```shell
cmake -DPUGS_PREFIX_PATH=[pugs_install_dir] [_PLUGIN_LOW__src_dir]
```
where `[pugs_install_dir]` has the same value as above and `[_PLUGIN_LOW__src_dir]`
is the plugin source directory that contains this `README.md` file.

Then to build the plugin, one runs
```shell
make
```

If anything runs fine, the dynamic library `lib_PLUGIN_NAME_.so` is
built.

# Using `_PLUGIN_NAME_`

In order to use the created plugin, one simply has to give the
location of `lib_PLUGIN_NAME_.so` to `pugs`. This is done by means of
environment variables. There are two possibilities:
- `PUGS_PLUGIN` contains a semicolumn separated list of plugin
  libraries,
- `PUGS_PLUGIN_DIR` contains a semicolumn separated list of path to
  plugin libraries.

Example
```shell
export PUGS_PLUGIN="/pathtoplugin/lib_PLUGIN_NAME_.so"
```
or
```shell
export PUGS_PLUGIN_DIR="/pathtoplugin1;/pathtoplugin2"
```

Then one launches `pugs` classically.
```shell
[pugs_install_dir]/bin/pugs [script.pgs]
```