Next

Prev

Prev-tail

Tail

Up

Chapter 18
Programs

 18.1 Environment Variables
  18.1.1 Search Path Variables
  18.1.2 Environment Variables
 18.2 Special Files
 18.3 urbi — Running an Urbi Server
  18.3.1 Options
  18.3.2 Quitting
 18.4 urbi-image — Querying Images from a Server
  18.4.1 Options
 18.5 urbi-launch — Running a UObject
  18.5.1 Invoking urbi-launch
  18.5.2 Examples
 18.6 urbi-send — Sending urbiscript Commands to a Server
 18.7 umake — Compiling UObject Components
  18.7.1 Invoking umake
  18.7.2 umake Wrappers

18.1 Environment Variables

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

18.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  

18.1.2 Environment Variables

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.
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.

18.2 Special Files

CLIENT.INI

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

global.u

If found in the URBI_PATH (see Section 18.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 20.23).

local.u

If found in the URBI_PATH (see Section 18.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’.

18.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 18.5).

18.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 18.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.

The options ‘-e’, ‘-f’ accumulate, and are run in the same Lobby (Section 20.32) 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  

18.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.

18.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.

18.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).

18.5 urbi-launch — Running a UObject

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

18.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 18.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 18.3.

18.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 18.3.2).

18.6 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.
-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.

18.7 umake — Compiling UObject Components

The umake programs builds loadable modules, UObjects, to be later run using urbi-launch (Section 18.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.

18.7.1 Invoking umake

Usage:

 
umake option... file...  

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

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.

Developer options

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

18.7.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 18.5). Same as ‘umake --shared-library’.