Next

Prev

Prev-tail

Tail

Up

Chapter 19
Programs

 19.1 Environment Variables
  19.1.1 Search Path Variables
  19.1.2 Environment Variables
 19.2 Special Files
 19.3 urbi — Running an Urbi Server
  19.3.1 Options
  19.3.2 Quitting
 19.4 urbi-image — Querying Images from a Server
  19.4.1 Options
 19.5 urbi-launch — Running a UObject
  19.5.1 Invoking urbi-launch
  19.5.2 Examples
 19.6 urbi-ping — Checking the Delays with a Server
  19.6.1 Options
 19.7 urbi-send — Sending urbiscript Commands to a Server
 19.8 umake — Compiling UObject Components
  19.8.1 Invoking umake
  19.8.2 umake Wrappers

19.1 Environment Variables

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

19.1.1 Search Path Variables

Some variables define search-paths, i.e., colon-separated lists of directories in which library files (urbiscript 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 URBI_PATH.

 
# 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 Jessies 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 Jessies place, and then in 
# /usr/local/urbi 
export URBI_PATH=:/home/jessie/urbi:/usr/local/urbi  

Windows Issues

On Windows too directories are separated by colons, but backslashes are used instead of forward-slashes. For instance

 
URBI_PATH=C:\cygwin\home\jessie\urbi:C:\cygwin\usr\local\urbi  

19.1.2 Environment Variables

The following variables control the way the log messages are displayed. They are meant for developers.

GD_COLOR

If set, force the use of colors in the logs, even if the output device does not seem to support them. See also GD_NO_COLOR.

GD_ENABLE_CATEGORY

If set, a comma-separated list of categories (e.g., UValue, Urbi) to display. All the others will be discarded. See also GD_DISABLE_CATEGORY.

GD_DISABLE_CATEGORY

If set, a comma-separated list of categories (e.g., UValue, Urbi) not to display. See also GD_ENABLE_CATEGORY.

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:

  1. NONE, no log messages at all.
  2. LOG, the default value.
  3. TRACE
  4. DEBUG
  5. DUMP, maximum verbosity.
GD_LOC

If set, display the location (file, line, function name) from which the log message was issued.

GD_NO_COLOR

If set, forbid the use of colors in the logs, even if the output device seems to support them, or if GD_COLOR is set.

GD_PID

If set, display the PID (Process Identity).

GD_THREAD

If set, display the thread identity.

GD_TIME

If set, display timestamps.

GD_TIMESTAMP_US

If set, display timestamps in microseconds.

The following variables control more high-level features, typically to override the default behavior.

URBI_PATH

The search-path for urbiscript source files (i.e., ‘*.u’ files).

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.

URBI_UOBJECT_PATH

The search-path for UObjects files. This is used by urbi-launch, by System.loadModule and System.loadLibrary.

URBI_UVAR_HOOK_CHANGED

If set, set UVar.hookChanged to false.

19.2 Special Files

CLIENT.INI

This is the obsolete name for ‘global.u’.

global.u

If found in the URBI_PATH (see Section 19.1), 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 Global (Section 21.24).

local.u

If found in the URBI_PATH (see Section 19.1), this file is loaded by every connection established with an Urbi server. This is the appropriate place for enhancements local to a lobby.

URBI.INI

This is the obsolete name for ‘global.u’.

19.3 urbi — Running an Urbi Server

The urbi program launches an Urbi server, for either batch, interactive, or network-based executions. It is subsumed by, but simpler to use than, urbi-launch (Section 19.5).

19.3.1 Options

General Options

-h’, ‘--help
 
Display the help message and exit successfully.
--version
 
Display version information and exit successfully.

Tuning

-d’, ‘--debug=level
 
Set the verbosity level of traces. See the GD_LEVEL documentation (Section 19.1.2).
-F’, ‘--fast
 
Ignore system time, go as fast as possible. Do not use this option unless you know exactly what you are doing.

The ‘--fast’ flag makes the kernel run the program in “simulated time”, as fast as possible. A 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:

 
{ sleep(2s); echo("after") } & { sleep(1s); echo("before") }; 
[000000463] *** before 
[000001463] *** after  

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; it does not preserve the program semantics.

-s’, ‘--stack-size=size
 
Set the coroutine stack size. The unit of size is KB; it defaults to 128.

This option should not be needed unless you have “stack exhausted” messages from urbi in which case you should try ‘--stack-size=512’ or more.

Alternatively you can define the environment variable URBI_STACK_SIZE. The option ‘--stack-size’ has precedence over the URBI_STACK_SIZE.

-q’, ‘--quiet
 
Do not send the welcome banner to incoming clients.

Networking

-H’, ‘--host=address
 
Set the address on which network connections are listened to. Typical values of address include:
localhost
only local connections are allowed (no other computer can reach this server).
127.0.0.1
same as localhost.
0.0.0.0
any IP v4 connection is allowed, including from remote computers.

Defaults to 0.0.0.0.

-P’, ‘--port=port
 
Set the port to listen incoming connections to. If port is -1, no networking. If port is 0, then the system will chose any available port (see ‘--port-file’). Defaults to -1.
-w’, ‘--port-file=file
 
When the system is up and running, and when it is ready for network connections, create the file named file which contains the number of the port the server listens to.

Execution

-e’, ‘--expression=exp
 
Send the urbiscript expression exp. No separator is added, you have to pass yours.
-f’, ‘--file=file
 
Send the contents of the file file. No separator is added, you have to pass yours.
-i’, ‘--interactive
 
Start an interactive session.

Enabled if no input was provided (i.e., none of ‘-e’/‘--expression’, ‘-f’/‘--file’, ‘-P’/‘--port’ was given).

-m’, ‘--module=module
 
Load the UObjectmodule.

The options ‘-e’, ‘-f’ accumulate, and are run in the same Lobby (Section 21.34) as ‘-i’ if used. In other words, the following session is valid:

 
# Create a file "two.u". 
$ echo "var two = 2;" >two.u 
$ urbi -q -e var one = 1; -f two.u -i 
[00000000] 1 
[00000000] 2 
one + two; 
[00000000] 3  

19.3.2 Quitting

To exit urbi, use the command System.shutdown.

If you are in interactive mode, you can also use the shortcut sequence C-d in the server lobby. The command Lobby.quit does not shutdown the server, it only closes the current lobby which closes the connection while in remote mode (using telnet for example), but only closes the interactive mode if performed on the server lobby.

On Unix systems, urbi handles the SIGINT signal (action performed when C-c is pressed). If you are in interactive mode, a first C-c kills the foreground job (or does nothing if no job is running on foreground).

For example consider the following piece of code:

 
every (4s) 
  echo("Hello world!");  

If you try to execute this code, you will notice that you can no longer execute commands, since the every job is foreground (because of the semicolon). Now if you press C-c, the every job is killed, all the pending commands you may have typed are cleared from the execution queue, and you get back with a working interactive mode.

 
every (1s) echo("Hello world!"); 
[00010181] *** Hello world! 
[00011181] *** Hello world! 
// This command is entered while the foreground job blocks the evaluation. 
// It waits to be executed. 
echo("done"); 
[00012181] *** Hello world! 
[00013181] *** Hello world! 
 
// Pressing Control-C here: 
[00014100:error] !!! received interruption, killing foreground job. 
// Note that the "echo" is not run, the command queue is flushed. 
 
// New commands are honored. 
echo("interrupted"); 
[00019709] *** interrupted  

A second C-c (or SIGINT) within the 1.5s after the first one tries to execute System.shutdown. This can take a while, in particular if you have remote UObjects, since a clean shutdown will first take care of disconnecting them cleanly.

 
// Two Control-C in a row. 
[00493865:error] !!! received interruption, killing foreground job. 
[00494672:error] !!! received interruption, shutting down.  

Pressing C-c a third time triggers the default behavior: killing the program in emergency, by-passing all the cleanups.

In non-interactive mode (after a Lobby.quit on the server lobby for example), the first C-c executes System.shutdown, and the second one triggers the default behavior.

19.4 urbi-image — Querying Images from a Server

 
urbi-image option...  

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

19.4.1 Options

General Options

-h’, ‘--help
 
Display the help message and exit successfully.
--version
 
Display version information and exit successfully.

Networking

-H’, ‘--host=host
 
Address to connect to.
-P’, ‘--port=port
 
Port to connect to.
--port-file=file
 
Connect to the port contained in the file file.

Tuning

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

19.5 urbi-launch — Running a UObject

The urbi-launch program launches an Urbi system. It is more general than urbi (Section 19.3): everything urbi can do, urbi-launch can do it too.

19.5.1 Invoking urbi-launch

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 ‘--’:

 
urbi-launch [urbi-launch-option...] module... [-- module-option...]  

The modules are looked for in the URBI_UOBJECT_PATH. The module extension (‘.so’, or ‘.dll’) does not need to be specified.

Urbi-launch options

-h’, ‘--help
 
Display the help message and exit successfully.
--version
 
Display version information and exit successfully.
-c’, ‘--customize=file
 
Start the Urbi server in file. This option is mostly for developers.
-d’, ‘--debug=level
 
Set the verbosity level of traces. See the GD_LEVEL documentation (Section 19.1.2).

Mode selection

-p’, ‘--plugin
 
Attach the module onto a currently running Urbi server (identified by host and port). This is equivalent to running loadModule("module") on the corresponding server.
-r’, ‘--remote
 
Run the modules as separated processes, connected to a running Urbi server (identified by host and port) via network connection.
-s’, ‘--start
 
Start an Urbi server with plugged-in modules. In this case, the module-option are exactly the options supported by urbi.

Networking urbi-launch supports the same networking options (‘--host’, ‘--port’, ‘--port-file’) as urbi, see Section 19.3.

19.5.2 Examples

To launch a fresh server in an interactive session with the UFactory UObject compiled as the file ‘factory.so’ (or ‘factory.dll’ plugged in, run:

 
urbi-launch --start urbi/factory -- --interactive  

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

 
urbi-launch --start --host 0.0.0.0 --port 54000 urbi/factory  

Since urbi-launch in server mode is basically the same as running the urbi program, both programs are quit the same way (see Section 19.3.2).

19.6 urbi-ping — Checking the Delays with a Server

 
urbi-ping option... [host] [interval] [count]  

Send “ping”s to an Urbi server, and report how long it took for “pong”s to come back.

19.6.1 Options

General Options

-h’, ‘--help
 
Display the help message and exit successfully.
--version
 
Display version information and exit successfully.

Networking

-H’, ‘--host=host
 
Address to connect to.
-P’, ‘--port=port
 
Port to connect to.
--port-file=file
 
Connect to the port contained in the file file.

Tuning

-c’, ‘--count=count
 
Number of pings to send. Pass 0 to send an unlimited number of pings. Defaults to 0.
-i’, ‘--interval=interval
 
Set the delays between pings, in milliseconds. Pass 0 to flood the connection. Defaults to 1000.

19.7 urbi-send — Sending urbiscript Commands to a Server

 
urbi-send option...  

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

-e’, ‘--expression=script
 
Send script to the server.
-f’, ‘--file=file
 
Send the contents of file to the server.
-m’, ‘--module=module
 
Load the UObjectmodule. This is equivalent to ‘[’style=varInString]—-e ’loadModule(”module”);’.
-h’, ‘--help
 
Display the help message and exit successfully.
-H’, ‘--host=host
 
Address to connect to.
-P’, ‘--port=port
 
Port to connect to.
--port-file=file
 
Connect to the port contained in the file file.
-Q’, ‘--quit
 
Disconnect from the server immediately after having sent all the commands. This is equivalent to ‘-e ’quit;’’ at the end of the options. 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, urbi-send prompts the user to hit C-c to end the connection.

--version
 
Display version information and exit successfully.

19.8 umake — Compiling UObject Components

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

19.8.1 Invoking umake

Usage:

 
umake option... file...  

Compile the file. The files can be of different kinds:

There are several environment variables that umake reads:

EXTRA_CPPFLAGS

Options passed to the preprocessor.

EXTRA_CXXFLAGS

Options passed to the C ++ compiler.

EXTRA_LDFLAGS

Options passed to the linker.

The arguments of umake may also include assignments, i.e., arguments of the type ‘var=val ’. The behavior depends on var, the name of the variable:

EXTRA_CPPFLAGS

Appended to the options passed to the preprocessor.

EXTRA_CXXFLAGS

Appended to the options passed to the C ++ compiler.

EXTRA_LDFLAGS

Appended to the options passed to the linker.

VPATH

Appended to the VPATH, i.e., the list of directories in which the sources are looked for.

Otherwise, the argument is passed as is to make.

General options

-D’, ‘--debug
 
Turn on shell debugging (set -x) to track umake problems.
-h’, ‘--help
 
Display the help message and exit successfully.
-q’, ‘--quiet
 
Produce no output except errors.
-V’, ‘--version
 
Display version information and exit successfully.
-v’, ‘--verbose
 
Report on what is done.

Compilation options

--deep-clean
 
Remove all building directories and exit.
-c’, ‘--clean
 
Clean building directory before compilation.
-j’, ‘--jobs=jobs
 
Specify the numbers of compilation commands to run simultaneously.
-l’, ‘--library
 
Produce a library, don’t link to a particular core.
-s’, ‘--shared
 
Produce a shared library loadable by any core.
-o’, ‘--output=file
 
Set the output file name.
-C’, ‘--core=core
 
Set the build type.
-H’, ‘--host=host
 
Set the destination host.
-m’, ‘--disable-automain
 
Do not add the main function.
--package=pkg
 
Use pkg-config to retrieve compilation flags (cflags and libs). Fails if pkg-config does not know about the package pkg.
-Ipath
 
Forwarded to the preprocessor (i.e., added to the EXTRA_CPPFLAGS).
-Lpath
 
Forwarded to the linker (i.e., added to the EXTRA_LDFLAGS).
-llib
 
Forwarded to the linker (i.e., added to the EXTRA_LDFLAGS).

Developer options

-p’, ‘--prefix=dir
 
Set library files location.
-P’, ‘--param-mk=file
 
Set ‘param.mk’ location.
-k’, ‘--kernel=dir
 
Set the kernel location.

19.8.2 umake Wrappers

As a convenience for common umake usages, some wrappers are provided:

umake-deepclean
— Cleaning
Clean the temporary files made by running umake with the same arguments. Same as ‘umake --deep-clean’.
umake-shared
— Compiling Shared UObjects
Build a shared object to be later run using urbi-launch (Section 19.5). Same as ‘umake --shared-library’.