source: roaraudio/doc/man1/roarpluginrunner.1 @ 5836:81ccac5ddc61

.\" roarpluginrunner.1:

.TH "roarpluginrunner" "1" "FIXME(DATE)" "RoarAudio" "System User's Manual: roarpluginrunner"

.SH NAME

roarpluginrunner \- Run RoarAudio plugins

.SH SYNOPSIS

roarpluginrunner [OPTIONS]... PLUGIN

.SH DESCRIPTION

This tool can be used to run RoarAudio plugins or report information about the plugin.
roarpluginrunner loads the plugins in a plugin container with the given parameters passed.
This allows you to run all universal plugins as well as some other plugins out side
a specific host. It can also be used for Testing the plugins.

There are three modes of operation: Running, Running as application and Explaining.
The first mode (Running) is what most host applications will do.
Running as application is different in the way that all parameters left on the command line
after the plugin name are parsed and passed to the plugin as plugin arguments.

In this mode parameters passed after the plugin name are split into key-value-pairs.
An option (beginning with two dashes) are passed as pair with the option name (the dashes) removed as key
and no value. If it contains a equality sign the part after it is passed as value.
Options with a single dash are split each letter into an own key-value-pair with only the key set.
Non-option arguments (with no dashes) are passed as value-only pairs.
After a pure double dash all parameters are passed as non-options with the double dash completely removed
from the key-value-array.

In the explain mode the plugin is loaded but not run. The meta information about the plugin are reported.
This includes true meta data like the name, authors and copyright but also technical meta data
like the host application's name the plugin is written for.

When the plugin uses symbols from the host directly the plugin may not be loaded into roarpluginrunner
because of the system's library loader limits. On GNU/Linux (and other POSIX like implementations)
this is only true if the plugin uses global variables of the host. Plugins using functions of the host
can still be loaded in this mode.

.SH "OPTIONS"

.TP
\fB-h \-\-help\fR
Prints a help message.

.TP
\fB-v \-\-verbose\fR
Be verbose. Can be used multiple times.

.TP
\fB--server SERVER\fR
Set default server to SERVER.

.TP
\fB--run\fR
Run plugin.

.TP
\fB--run-as-application\fR
Same as \-\-run except all tailing arguments are passed to the plugin.
This is also used by \fBroarpluginapplication\fR(1).

.TP
\fB--explain\fR
Explain plugin. This lists all details about the plugin without actually running it.

.TP
\fB--appname NAME\fR
Sets the appname.

.TP
\fB--abiversion ABI\fR
Set the ABI version.

.TP
\fB--args ARGS\fR
Set plugin arguments.

.SH "RUNNER OPTIONS"

.TP
\fB--option-touch\fR
Do not keep the plugin running: Do a single UPDATE cycle.

.TP
\fB--option-no-touch\fR
Disable touch option.

.TP
\fB--option-about\fR
Show an about dialog after startup.

.TP
\fB--option-no-about\fR
Disable about option.

.TP
\fB--option-help\fR
Show onlion help after startup.

.TP
\fB--option-no-help\fR
Disable help option.

.TP
\fB--option-preferences\fR
Show preferences dialog after startup.

.TP
\fB--option-no-preferences\fR
Disable preferences option.

.SH "CPI OPTIONS"

.TP
\fB-t \-\-tcp\fR
Use TCP listen socket.

.TP
\fB-u \-\-unix\fR
Use UNIX Domain listen socket (default).

.TP
\fB-n \-\-decnet\fR
use DECnet listen socket.

.TP
\fB--port PORT\fR
TCP Port to bind to. Only in case of TCP listen sockets.

.TP
\fB--bind ADDR\fR
Node/Hostname/Path to bind to.

.TP
\fB--proto PROTO\fR
Use PROTO as protocol on listen or client socket.

.TP
\fB--new-sock\fR
Parameters for new socket follow.

.TP
\fB--client-fh FH\fR
Comunicate with a client over this handle.

.SH "BUGS"
\fB--client-fh\fR may not work as expected.

.SH "SEE ALSO"
\fBroarpluginapplication\fR(1),
\fBroartips\fR(7),
\fBlibroar\fR(7),
\fBRoarAudio\fR(7).

.SH "HISTORY"

For history information see \fBRoarAudio\fR(7).

.\" ll