<commit_before>\newcommand{\optionDebug}{
  Set the verbosity level of traces.
  This option is mostly for developers, but it is very useful when
  tracking problems such as a UObject that fails to load properly.
  Valid values for \var{level} are, in increasing verbosity order:
  \begin{sublist}
    \begin{enumerate}
    \item \code{NONE}, no log messages at all.
    \item \code{LOG}, the default value.
    \item \code{TRACE}
    \item \code{DEBUG}
    \item \code{DUMP}, maximum verbosity.
    \end{enumerate}
  \end{sublist}
}
\newcommand{\optionHelp}
  {Display the help message and exit successfully.}

\newcommand{\optionVersion}
  {Display version information and exit successfully.}

\chapter{Programs}
\label{sec:tools}

\section{Environment Variables}
\label{sec:tools:envvars}

There is a number of environment variables that alter the behavior of
the \urbi tools.

\subsection{Search Path Variables}

Some variables define \dfn[search-path]{search-paths}, i.e.,
colon-separated lists of directories in which library files (\us
programs, UObjects and so forth) are looked for.

The tools have predefined values for these variables which are
tailored for your installation --- so that \urbi tools can be run
without any special adjustment.  In order to provide the user with a
means to override or extend these built-in values, the path variables
support a special syntax: a lone colon specifies where the standard
search path must be inserted.  See the following examples about
\env{URBI\_PATH}.

\begin{shell}
# Completely override the system path.  First look for files in
# /home/jessie/urbi, then in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi

# Prepend the previous path to the default path.  This is dangerous as
# it may result in some standard files being hidden.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi:

# First look in Jessie's directory, then the default location, and
# finally in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi::/usr/local/urbi

# Extend the default path, i.e., files that are not found in the
# default path will be looked for in Jessie's place, and then in
# /usr/local/urbi
export URBI_PATH=:/home/jessie/urbi:/usr/local/urbi
\end{shell}

\begin{windows}
  On Windows too directories are separated by colons, but backslashes
  are used instead of forward-slashes.  For instance
\begin{shell}
URBI_PATH=C:\cygwin\home\jessie\urbi:C:\cygwin\usr\local\urbi
\end{shell}
\end{windows}

\subsection{Environment Variables}
\begin{envs}
\item[URBI\_PATH] The search-path for \us source files (i.e.,
  \file{*.u} files).

\item[URBI\_ROOT] The \urbi SDK is relocatable: its components know the
  relative location of each other.  Yet they need to ``guess'' the
  \urbi root, i.e., the path to the directory that contains the files.
  This variable also to override that guess.  Do not use it unless you
  know exactly what you are doing.

\item[URBI\_UOBJECT\_PATH] The search-path for UObjects files.
  This is used by \command{urbi-launch}, by
  \lstinline|System.loadModule| and \lstinline|System.loadLibrary|.
\end{envs}

\section{Special Files}
\label{sec:tools:files}

\begin{files}
\item[CLIENT.INI] This is the obsolete name for \file{global.u}.

\item[global.u] If found in the \env{URBI\_PATH} (see
  \autoref{sec:tools:envvars}), this file is loaded by \urbi server upon
  start-up.  It is the appropriate place to install features you
  mean to provide to all the users of the server.  It is will be
  loaded via a special system connection, with its own private lobby.
  Therefore, purely local definitions will not be reachable from
  users; global modifications should be made in globally visible
  objects, say \refObject{Global}.

\item[local.u] If found in the \env{URBI\_PATH} (see
  \autoref{sec:tools:envvars}), this file is loaded by every
  connection established with an \urbi server.  This is the
  appropriate place for enhancements local to a lobby.

\item[URBI.INI] This is the obsolete name for \file{global.u}.
\end{files}

\section{\command{urbi} --- Running an Urbi Server}
\label{sec:tools:urbi}

The \command{urbi} program launches an \urbi server, for either batch,
interactive, or network-based executions.  It is subsumed by, but
simpler to use than, \command{urbi-launch}
(\autoref{sec:tools:urbi-launch}).

\subsection{Options}

\begin{options}[General Options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\end{options}

\begin{options}[Tuning]
\item[d]{debug=\var{level}} \optionDebug
\item[F]{fast}
  Ignore system time, go as fast as possible.  Do not use this option
  unless you know exactly what you are doing.

  The \option{--fast} flag makes the kernel run the program in
  ``simulated time'', as fast as possible. A \lstinline|sleep| in fast
  mode will not actually wait (from the wall-clock point of view), but
  the kernel will internally increase its simulated time.

  For instance, the following session behaves equally in fast and
  non-fast mode:

\begin{urbiscript}[firstnumber=1]
{ sleep(2s); echo("after") } & { sleep(1s); echo("before") };
[000000463] *** before
[000001463] *** after
\end{urbiscript}

  \noindent
  However, in non fast mode the execution will take two seconds (wall
  clock time), while it be instantaneous in fast mode. This option was
  designed for testing purpose; \emph{it does not preserve the program
    semantics}.

\item[s]{stack-size=\var{size}} Set the coroutine \dfn{stack size}.
  The unit of \var{size} is KB; it defaults to 128.

  This option should not be needed unless you have ``stack exhausted''
  messages from \command{urbi} in which case you should try
  \option{--stack-size=512} or more.

  Alternatively you can define the environment variable
  \env{URBI\_STACK\_SIZE}.  The option \option{--stack-size} has
  precedence over the \env{URBI\_STACK\_SIZE}.

\item[q]{quiet} Do not send the welcome banner to incoming clients.
\end{options}

\begin{options}[Networking]
\item[H]{host=\var{address}} Set the \var{address} on which network
  connections are listened to.  Typical values of \var{address}
  include:
  \begin{sublist}
    \begin{description}
    \item[localhost] only local connections are allowed (no other
      computer can reach this server).
    \item[127.0.0.1] same as \code{localhost}.
    \item[0.0.0.0] any IP v4 connection is allowed, including from
      remote computers.
  \end{description}
  \end{sublist}
  Defaults to \code{0.0.0.0}.
\item[P]{port=\var{port}} Set the port to listen incoming
  connections to.  If \var{port} is \code{-1}, no networking.  If
  \var{port} is \code{0}, then the system will chose any available
  port (see \option{--port-file}).  Defaults to \code{-1}.
\item[w]{port-file=\var{file}} When the system is up and running,
  and when it is ready for network connections, create the file named
  \var{file} which contains the number of the port the server listens
  to.
\end{options}


\begin{options}[Execution]
\item[e]{expression=\var{exp}} Send the \us expression \var{exp}.
  No separator is added, you have to pass yours.
\item[f]{file=\var{file}} Send the contents of the file \var{file}.
  No separator is added, you have to pass yours.
\item[i]{interactive} Start an interactive session.
\end{options}

The options \option{-e}, \option{-f} accumulate, and are run in the
same \refObject{Lobby} as \option{-i} if used.  In other words, the
following session is valid:

\begin{shell}[alsolanguage={[interactive]Urbi}]
# Create a file "two.u".
$ echo "var two = 2;" >two.u
# urbi -e 'var one = 1;' -f two.u -i
[00000000] 1
[00000000] 2
one + two;
[00000000] 3
\end{shell}%$

\section{\command{urbi-image} --- Querying Images from a Server}
\label{sec:tools:urbi-image}

\begin{shell}
urbi-image \var{option}...
\end{shell}

Connect to an \urbi server, and fetch images from it, for instance
from its camera.

\subsection{Options}

\begin{options}[General Options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\end{options}

\begin{options}[Networking]
\item[H]{host=\var{host}} Address to connect to.
\item[P]{port=\var{port}} Port to connect to.
\item{port-file=\var{file}} Connect to the port contained in the file
  \var{file}.
\end{options}

\begin{options}[Tuning]
\item[p]{period=\var{period}} Specify the period, in millisecond, at
  which images are queried.
\item[F]{format=\var{format}} Select format of the image (\samp{rgb},
  \samp{ycrcb}, \samp{jpeg}, \samp{ppm}).
\item[r]{reconstruct} Use reconstruct mode (for aibo).
\item[j]{jpeg=\var{factor}} JPEG compression factor (from 0 to 100,
  defaults to 70).
\item[d]{device=\var{device}} Query image on \var{device}.val
  (default: \code{camera}).
\item[o]{output=\var{file}} Query and save one image to \var{file}.
\item[R]{resolution=\var{resolution}} Select resolution of the image
  (0=biggest).
\item[s]{scale=\var{factor}} Rescale image with given \var{factor}
  (display only).
\end{options}


\section{\command{urbi-launch} --- Running a UObject}
\label{sec:tools:urbi-launch}

The \command{urbi-launch} program launches an \urbi system.  It is
more general than \command{urbi} (\autoref{sec:tools:urbi}):
everything \command{urbi} can do, \command{urbi-launch} can do it too.

\subsection{Invoking \command{urbi-launch}}

\command{urbi-launch} launches UObjects, either in plugged-in mode, or
in remote mode.  Since UObjects can also accept options, the command
line features two parts, separated by \samp{--}:

\begin{shell}
urbi-launch [\var{urbi-launch-option}...] \var{module}... [-- \var{module-option}...]
\end{shell}

The \var{module}s are looked for in the \env{URBI\_UOBJECT\_PATH}.

\begin{options}[Urbi-launch options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\item[c]{customize=\var{file}} Start the \urbi server in
  \var{file}.  This option is mostly for developers.
\item[d]{debug=\var{level}} \optionDebug
\end{options}

\begin{options}[Mode selection]
% !!! \lstinline|loadModule("\var{module}")| does not escape the \var
% because it is inside a string.
\item[p]{plugin} Attach the \var{module} onto a currently running
  \urbi server (identified by \var{host} and \var{port}).  This is
  equivalent to running \lstinline|loadModule("module")| on the
  corresponding server.

\item[r]{remote} Run the \var{modules} as separated processes,
  connected to a running Urbi server (identified by \var{host} and
  \var{port}) via network connection.

\item[s]{start} Start an Urbi server with plugged-in
  \var{modules}.  In this case, the \var{module-option} are exactly
  the options supported by \command{urbi}.
\end{options}

\paragraph{Networking}
\command{urbi-launch} supports the same networking options
(\option{--host}, \option{--port}, \option{--port-file}) as
\command{urbi}, see \autoref{sec:tools:urbi}.

\subsection{Examples}

To launch a fresh server in an interactive session with the
\lstinline|UFactory| UObject compiled as the file \file{factory.so}
(or \file{factory.dll} plugged in, run:

\begin{shell}
urbi-launch --start ufactory -- --interactive
\end{shell}

To start an \urbi server accepting connections on the local port 54000
from any remote host, with \lstinline|UFactory| plugged in, run:

\begin{shell}
urbi-launch --start --host 0.0.0.0 --port 54000 ufactory
\end{shell}


\section{\command{urbi-send} --- Sending \us Commands to a Server}
\label{sec:tools:urbi-send}

\begin{shell}
urbi-send \var{option}...
\end{shell}

Connect to an \urbi server, and send commands or file contents to it.
Stay connected, until server disconnection, or user interruption (such
as \key{C-c} under a Unix terminal).

\begin{options}
\item[e]{expression=\var{script}} Send \var{script} to the server.
\item[f]{file=\var{file}} Send the contents of \var{file} to the
  server.
\item[h]{help} \optionHelp
\item[H]{host=\var{host}} Address to connect to.
\item[P]{port=\var{port}} Port to connect to.
\item{port-file=\var{file}} Connect to the port contained in the file
  \var{file}.
\item[q]{quit} Disconnect from the server immediately after having
  sent all the commands.  This is equivalent to \samp{-e 'quit;'}.
  This is inappropriate if code running in background is expected to
  deliver its result asynchronously: the connection will be closed
  before the result was sent.

  Without this option, \command{urbi-send} prompts the user to hit
  \key{C-c} to end the connection.
\item{version} \optionVersion
\end{options}


\section{\command{umake} --- Compiling UObject Components}
\label{sec:tools:umake}

The \command{umake} programs builds loadable modules, UObjects, to be
later run using \command{urbi-launch}
(\autoref{sec:tools:urbi-launch}).  Using it is not mandatory: users
familiar with their compilation tools will probably prefer using them
directly.  Yet \command{umake} makes things more uniform and simpler,
at the cost of less control.

\subsection{Invoking \command{umake}}
\label{sec:tools:umake:invoke}

Usage:
\begin{shell}
umake \var{option}... \var{file}...
\end{shell}

Compile the \var{file}.  The \var{files} can be of different kinds:
\begin{itemize}
\item objects files (\file{*.o}, \file{*.obj} and so forth) and linked
  into the result.
\item libraries (\file{*.a}) and linked into the result.
\item source files (\file{*.cc}, \file{*.cpp}, \file{*.c}, \file{*.C})
  are compiled.
\item header files (\file{*.h}, \file{*.hh}, \file{*.hxx},
  \file{*.hpp}) are \emph{not} compiled, but used as dependencies: if
  a header file is changed, the next \command{umake} run will actually
  recompile.
\item directories are recursively traversed, and files of the above
  types are gathered as if they were given on the command line.
\end{itemize}

\begin{options}[General options]
\item[D]{debug} Turn on shell debugging (\lstinline|set -x|) to
  track \command{umake} problems.
\item[h]{help} \optionHelp
\item[q]{quiet} Produce no output except errors.
\item[v]{version} \optionVersion
\item[V]{verbose} Report on what is done.
\end{options}

\begin{options}[Compilation options]
\item{deep-clean} Remove all building directories and exit.
\item[c]{clean} Clean building directory before compilation.
\item[j]{jobs=\var{jobs}} Specify the numbers of compilation
  commands to run simultaneously.
\item[l]{library} Produce a library, don't link to a particular
  core.
\item[s]{shared-library} Produce a shared library loadable by any
  core.
\item[o]{output=\var{file}} Set the output file name.
\item[C]{core=\var{core}} Set the build type.
\item[H]{host=\var{host}} Set the destination host.
\item[m]{disable-automain} Do not add the \lstinline|main| function.
\end{options}

\begin{options}[Developer options]
\item[p]{prefix=\var{dir}} Set library files location.
\item[P]{param-mk=\var{file}} Set \file{param.mk} location.
\item[k]{kernel=\var{dir}} Set the kernel location.
\end{options}


\subsection{\command{umake} Wrappers}
\label{sec:tools:umake:wrappers}

As a convenience for common \command{umake} usages, some wrappers are
provided:
\begin{description}
\item[\command{umake-deepclean}] --- Cleaning\\
  Clean the temporary files made by running \command{umake} with the
  same arguments.  Same as \samp{umake --deep-clean}.
\item[\command{umake-shared}] --- Compiling Shared UObjects\\
  Build a shared object to be later run using \command{urbi-launch}
  (\autoref{sec:tools:urbi-launch}).  Same as \samp{umake
    --shared-library}.
\end{description}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../urbi-sdk"
%%% ispell-dictionary: "american"
%%% ispell-personal-dictionary: "../urbi.dict"
%%% fill-column: 76
%%% End:
<commit_msg>doc: document GD_LEVEL.<commit_after>\newcommand{\optionDebug}
  {Set the verbosity level of traces.  See the \env{GD\_LEVEL} documentation
   (\autoref{sec:tools:env}).}

\newcommand{\optionHelp}
  {Display the help message and exit successfully.}

\newcommand{\optionVersion}
  {Display version information and exit successfully.}

\chapter{Programs}
\label{sec:tools}

\section{Environment Variables}
\label{sec:tools:envvars}

There is a number of environment variables that alter the behavior of
the \urbi tools.

\subsection{Search Path Variables}

Some variables define \dfn[search-path]{search-paths}, i.e.,
colon-separated lists of directories in which library files (\us
programs, UObjects and so forth) are looked for.

The tools have predefined values for these variables which are
tailored for your installation --- so that \urbi tools can be run
without any special adjustment.  In order to provide the user with a
means to override or extend these built-in values, the path variables
support a special syntax: a lone colon specifies where the standard
search path must be inserted.  See the following examples about
\env{URBI\_PATH}.

\begin{shell}
# Completely override the system path.  First look for files in
# /home/jessie/urbi, then in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi

# Prepend the previous path to the default path.  This is dangerous as
# it may result in some standard files being hidden.
export URBI_PATH=/home/jessie/urbi:/usr/local/urbi:

# First look in Jessie's directory, then the default location, and
# finally in /usr/local/urbi.
export URBI_PATH=/home/jessie/urbi::/usr/local/urbi

# Extend the default path, i.e., files that are not found in the
# default path will be looked for in Jessie's place, and then in
# /usr/local/urbi
export URBI_PATH=:/home/jessie/urbi:/usr/local/urbi
\end{shell}

\begin{windows}
  On Windows too directories are separated by colons, but backslashes
  are used instead of forward-slashes.  For instance
\begin{shell}
URBI_PATH=C:\cygwin\home\jessie\urbi:C:\cygwin\usr\local\urbi
\end{shell}
\end{windows}

\subsection{Environment Variables}
\label{sec:tools:env}
\begin{envs}
\item[GD\_LEVEL] Set the verbosity level of traces.  This environment
  variable is meant for the developers of \urbi SDK, yet it is very useful
  when tracking problems such as a UObject that fails to load properly.
  Valid values are, in increasing verbosity order:
  \begin{enumerate}
  \item \code{NONE}, no log messages at all.
  \item \code{LOG}, the default value.
  \item \code{TRACE}
  \item \code{DEBUG}
  \item \code{DUMP}, maximum verbosity.
  \end{enumerate}

\item[URBI\_PATH] The search-path for \us source files (i.e.,
  \file{*.u} files).

\item[URBI\_ROOT] The \urbi SDK is relocatable: its components know the
  relative location of each other.  Yet they need to ``guess'' the
  \urbi root, i.e., the path to the directory that contains the files.
  This variable also to override that guess.  Do not use it unless you
  know exactly what you are doing.

\item[URBI\_UOBJECT\_PATH] The search-path for UObjects files.
  This is used by \command{urbi-launch}, by
  \lstinline|System.loadModule| and \lstinline|System.loadLibrary|.
\end{envs}

\section{Special Files}
\label{sec:tools:files}

\begin{files}
\item[CLIENT.INI] This is the obsolete name for \file{global.u}.

\item[global.u] If found in the \env{URBI\_PATH} (see
  \autoref{sec:tools:envvars}), this file is loaded by \urbi server upon
  start-up.  It is the appropriate place to install features you
  mean to provide to all the users of the server.  It is will be
  loaded via a special system connection, with its own private lobby.
  Therefore, purely local definitions will not be reachable from
  users; global modifications should be made in globally visible
  objects, say \refObject{Global}.

\item[local.u] If found in the \env{URBI\_PATH} (see
  \autoref{sec:tools:envvars}), this file is loaded by every
  connection established with an \urbi server.  This is the
  appropriate place for enhancements local to a lobby.

\item[URBI.INI] This is the obsolete name for \file{global.u}.
\end{files}

\section{\command{urbi} --- Running an Urbi Server}
\label{sec:tools:urbi}

The \command{urbi} program launches an \urbi server, for either batch,
interactive, or network-based executions.  It is subsumed by, but
simpler to use than, \command{urbi-launch}
(\autoref{sec:tools:urbi-launch}).

\subsection{Options}

\begin{options}[General Options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\end{options}

\begin{options}[Tuning]
\item[d]{debug=\var{level}} \optionDebug
\item[F]{fast}
  Ignore system time, go as fast as possible.  Do not use this option
  unless you know exactly what you are doing.

  The \option{--fast} flag makes the kernel run the program in
  ``simulated time'', as fast as possible. A \lstinline|sleep| in fast
  mode will not actually wait (from the wall-clock point of view), but
  the kernel will internally increase its simulated time.

  For instance, the following session behaves equally in fast and
  non-fast mode:

\begin{urbiscript}[firstnumber=1]
{ sleep(2s); echo("after") } & { sleep(1s); echo("before") };
[000000463] *** before
[000001463] *** after
\end{urbiscript}

  \noindent
  However, in non fast mode the execution will take two seconds (wall
  clock time), while it be instantaneous in fast mode. This option was
  designed for testing purpose; \emph{it does not preserve the program
    semantics}.

\item[s]{stack-size=\var{size}} Set the coroutine \dfn{stack size}.
  The unit of \var{size} is KB; it defaults to 128.

  This option should not be needed unless you have ``stack exhausted''
  messages from \command{urbi} in which case you should try
  \option{--stack-size=512} or more.

  Alternatively you can define the environment variable
  \env{URBI\_STACK\_SIZE}.  The option \option{--stack-size} has
  precedence over the \env{URBI\_STACK\_SIZE}.

\item[q]{quiet} Do not send the welcome banner to incoming clients.
\end{options}

\begin{options}[Networking]
\item[H]{host=\var{address}} Set the \var{address} on which network
  connections are listened to.  Typical values of \var{address}
  include:
  \begin{sublist}
    \begin{description}
    \item[localhost] only local connections are allowed (no other
      computer can reach this server).
    \item[127.0.0.1] same as \code{localhost}.
    \item[0.0.0.0] any IP v4 connection is allowed, including from
      remote computers.
  \end{description}
  \end{sublist}
  Defaults to \code{0.0.0.0}.
\item[P]{port=\var{port}} Set the port to listen incoming
  connections to.  If \var{port} is \code{-1}, no networking.  If
  \var{port} is \code{0}, then the system will chose any available
  port (see \option{--port-file}).  Defaults to \code{-1}.
\item[w]{port-file=\var{file}} When the system is up and running,
  and when it is ready for network connections, create the file named
  \var{file} which contains the number of the port the server listens
  to.
\end{options}


\begin{options}[Execution]
\item[e]{expression=\var{exp}} Send the \us expression \var{exp}.
  No separator is added, you have to pass yours.
\item[f]{file=\var{file}} Send the contents of the file \var{file}.
  No separator is added, you have to pass yours.
\item[i]{interactive} Start an interactive session.
\end{options}

The options \option{-e}, \option{-f} accumulate, and are run in the
same \refObject{Lobby} as \option{-i} if used.  In other words, the
following session is valid:

\begin{shell}[alsolanguage={[interactive]Urbi}]
# Create a file "two.u".
$ echo "var two = 2;" >two.u
# urbi -e 'var one = 1;' -f two.u -i
[00000000] 1
[00000000] 2
one + two;
[00000000] 3
\end{shell}%$

\section{\command{urbi-image} --- Querying Images from a Server}
\label{sec:tools:urbi-image}

\begin{shell}
urbi-image \var{option}...
\end{shell}

Connect to an \urbi server, and fetch images from it, for instance
from its camera.

\subsection{Options}

\begin{options}[General Options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\end{options}

\begin{options}[Networking]
\item[H]{host=\var{host}} Address to connect to.
\item[P]{port=\var{port}} Port to connect to.
\item{port-file=\var{file}} Connect to the port contained in the file
  \var{file}.
\end{options}

\begin{options}[Tuning]
\item[p]{period=\var{period}} Specify the period, in millisecond, at
  which images are queried.
\item[F]{format=\var{format}} Select format of the image (\samp{rgb},
  \samp{ycrcb}, \samp{jpeg}, \samp{ppm}).
\item[r]{reconstruct} Use reconstruct mode (for aibo).
\item[j]{jpeg=\var{factor}} JPEG compression factor (from 0 to 100,
  defaults to 70).
\item[d]{device=\var{device}} Query image on \var{device}.val
  (default: \code{camera}).
\item[o]{output=\var{file}} Query and save one image to \var{file}.
\item[R]{resolution=\var{resolution}} Select resolution of the image
  (0=biggest).
\item[s]{scale=\var{factor}} Rescale image with given \var{factor}
  (display only).
\end{options}


\section{\command{urbi-launch} --- Running a UObject}
\label{sec:tools:urbi-launch}

The \command{urbi-launch} program launches an \urbi system.  It is
more general than \command{urbi} (\autoref{sec:tools:urbi}):
everything \command{urbi} can do, \command{urbi-launch} can do it too.

\subsection{Invoking \command{urbi-launch}}

\command{urbi-launch} launches UObjects, either in plugged-in mode, or
in remote mode.  Since UObjects can also accept options, the command
line features two parts, separated by \samp{--}:

\begin{shell}
urbi-launch [\var{urbi-launch-option}...] \var{module}... [-- \var{module-option}...]
\end{shell}

The \var{module}s are looked for in the \env{URBI\_UOBJECT\_PATH}.

\begin{options}[Urbi-launch options]
\item[h]{help} \optionHelp
\item{version} \optionVersion
\item[c]{customize=\var{file}} Start the \urbi server in
  \var{file}.  This option is mostly for developers.
\item[d]{debug=\var{level}} \optionDebug
\end{options}

\begin{options}[Mode selection]
% !!! \lstinline|loadModule("\var{module}")| does not escape the \var
% because it is inside a string.
\item[p]{plugin} Attach the \var{module} onto a currently running
  \urbi server (identified by \var{host} and \var{port}).  This is
  equivalent to running \lstinline|loadModule("module")| on the
  corresponding server.

\item[r]{remote} Run the \var{modules} as separated processes,
  connected to a running Urbi server (identified by \var{host} and
  \var{port}) via network connection.

\item[s]{start} Start an Urbi server with plugged-in
  \var{modules}.  In this case, the \var{module-option} are exactly
  the options supported by \command{urbi}.
\end{options}

\paragraph{Networking}
\command{urbi-launch} supports the same networking options
(\option{--host}, \option{--port}, \option{--port-file}) as
\command{urbi}, see \autoref{sec:tools:urbi}.

\subsection{Examples}

To launch a fresh server in an interactive session with the
\lstinline|UFactory| UObject compiled as the file \file{factory.so}
(or \file{factory.dll} plugged in, run:

\begin{shell}
urbi-launch --start ufactory -- --interactive
\end{shell}

To start an \urbi server accepting connections on the local port 54000
from any remote host, with \lstinline|UFactory| plugged in, run:

\begin{shell}
urbi-launch --start --host 0.0.0.0 --port 54000 ufactory
\end{shell}


\section{\command{urbi-send} --- Sending \us Commands to a Server}
\label{sec:tools:urbi-send}

\begin{shell}
urbi-send \var{option}...
\end{shell}

Connect to an \urbi server, and send commands or file contents to it.
Stay connected, until server disconnection, or user interruption (such
as \key{C-c} under a Unix terminal).

\begin{options}
\item[e]{expression=\var{script}} Send \var{script} to the server.
\item[f]{file=\var{file}} Send the contents of \var{file} to the
  server.
\item[h]{help} \optionHelp
\item[H]{host=\var{host}} Address to connect to.
\item[P]{port=\var{port}} Port to connect to.
\item{port-file=\var{file}} Connect to the port contained in the file
  \var{file}.
\item[q]{quit} Disconnect from the server immediately after having
  sent all the commands.  This is equivalent to \samp{-e 'quit;'}.
  This is inappropriate if code running in background is expected to
  deliver its result asynchronously: the connection will be closed
  before the result was sent.

  Without this option, \command{urbi-send} prompts the user to hit
  \key{C-c} to end the connection.
\item{version} \optionVersion
\end{options}


\section{\command{umake} --- Compiling UObject Components}
\label{sec:tools:umake}

The \command{umake} programs builds loadable modules, UObjects, to be
later run using \command{urbi-launch}
(\autoref{sec:tools:urbi-launch}).  Using it is not mandatory: users
familiar with their compilation tools will probably prefer using them
directly.  Yet \command{umake} makes things more uniform and simpler,
at the cost of less control.

\subsection{Invoking \command{umake}}
\label{sec:tools:umake:invoke}

Usage:
\begin{shell}
umake \var{option}... \var{file}...
\end{shell}

Compile the \var{file}.  The \var{files} can be of different kinds:
\begin{itemize}
\item objects files (\file{*.o}, \file{*.obj} and so forth) and linked
  into the result.
\item libraries (\file{*.a}) and linked into the result.
\item source files (\file{*.cc}, \file{*.cpp}, \file{*.c}, \file{*.C})
  are compiled.
\item header files (\file{*.h}, \file{*.hh}, \file{*.hxx},
  \file{*.hpp}) are \emph{not} compiled, but used as dependencies: if
  a header file is changed, the next \command{umake} run will actually
  recompile.
\item directories are recursively traversed, and files of the above
  types are gathered as if they were given on the command line.
\end{itemize}

\begin{options}[General options]
\item[D]{debug} Turn on shell debugging (\lstinline|set -x|) to
  track \command{umake} problems.
\item[h]{help} \optionHelp
\item[q]{quiet} Produce no output except errors.
\item[v]{version} \optionVersion
\item[V]{verbose} Report on what is done.
\end{options}

\begin{options}[Compilation options]
\item{deep-clean} Remove all building directories and exit.
\item[c]{clean} Clean building directory before compilation.
\item[j]{jobs=\var{jobs}} Specify the numbers of compilation
  commands to run simultaneously.
\item[l]{library} Produce a library, don't link to a particular
  core.
\item[s]{shared-library} Produce a shared library loadable by any
  core.
\item[o]{output=\var{file}} Set the output file name.
\item[C]{core=\var{core}} Set the build type.
\item[H]{host=\var{host}} Set the destination host.
\item[m]{disable-automain} Do not add the \lstinline|main| function.
\end{options}

\begin{options}[Developer options]
\item[p]{prefix=\var{dir}} Set library files location.
\item[P]{param-mk=\var{file}} Set \file{param.mk} location.
\item[k]{kernel=\var{dir}} Set the kernel location.
\end{options}


\subsection{\command{umake} Wrappers}
\label{sec:tools:umake:wrappers}

As a convenience for common \command{umake} usages, some wrappers are
provided:
\begin{description}
\item[\command{umake-deepclean}] --- Cleaning\\
  Clean the temporary files made by running \command{umake} with the
  same arguments.  Same as \samp{umake --deep-clean}.
\item[\command{umake-shared}] --- Compiling Shared UObjects\\
  Build a shared object to be later run using \command{urbi-launch}
  (\autoref{sec:tools:urbi-launch}).  Same as \samp{umake
    --shared-library}.
\end{description}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../urbi-sdk"
%%% ispell-dictionary: "american"
%%% ispell-personal-dictionary: "../urbi.dict"
%%% fill-column: 76
%%% End:

{'fraction_non_alphanumeric': 0.12748953038585722, 'fraction_numerical': 0.006201847767015121, 'mean_word_length': 4.26278600269179, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 6, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2181418', 'n_tokens_mistral': 10261, 'n_tokens_neox': 9923, 'n_words': 3568}