View source for Uno/Binary/Spec/Bootstrapping

Type: Specification State: final Claim: required

While introducing a simple concept for UNO bootstrapping (see my mail in the udk.dev list), I noticed that there is a need for a general bootstrap-argument-passing-mechanism. At the moment we have different locations where some kind of context knowledge for bootstrapping is needed:
* '''the office:''' needs to find the sversionrc (sversion.ini) to find its installation 
* '''configuration:''' needs a bootstraprc (bootstrap.ini) to find the appropriate user configuration (e.g. local, portal, remote, ...) 
* '''UNO (new)'''': to simplify UNO bootstrapping, it is going to support UNO_SERVICES, UNO_TYPES and UNO_WRITERDB variables (see below) 
* '''java:''' instead of using a javarc (java.ini) the needed parameters (e.g. the classpath) can be passed via environment variables.

Different, but similar concepts are used (e.g. a file with an entry which points to a special directory). I would like to unify these concepts and to use one mechanism for bootstrapping. I would also like to be able to configure the bootstrapping via command line arguments or via environment variables (which, for instance, may be set by setsolar).

==Two Tiers==
During discussion on OpenOffice.org, the idea of a two tier approach emerged. This idea defines two general purpose mechanisms, which, put on each other, seem to fulfil all requirements needed to default bootstrap any UNO application, including OpenOffice.org and OpenOffice.org Setup.

The two tiers are:
* a general bootstrap argument passing mechanism, which also allows to find user dependent global data, this mechanism is placed in sal/rtl.
* default bootstrapping of an initial UNO context this is a higher level mechanism, which uses the low level bootstrap argument passing. It is placed in 'cppuhelper'.

==Bootstrap Arguments==
A mechanism to allow differentiated access to bootstrap arguments at the runtime library (RTL) level is needed.

===Access Bootstrap Arguments via the RTL===
The following two functions give access to any bootstrap arguments:
<code>[cpp]

sal_Bool SAL_CALL rtl_bootstrap_get( rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault );

void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pName );

</code>

The first function gives direct access to any bootstrap parameter, which may be passed to the application. Four ways are defined by which parameters can be given to the application. It follows by precedence ordered list of the four ways:
* parameters may get passed by command line arguments
* parameters may get passed by an optional .ini/rc file
* parameters may get passed by environment variables
* parameters may get passed as default values for 'rtl_bootstrap_get'

Each of these methods is used exclusive, which means, the above mechanism are tried in order and the search for a bootstrap argument stops with the first one providing a result. Bootstrap arguments which should be passed via command line, must have a special shape, so that they are distinguishable from other command line arguments:
<pre>
myapp.bin -env:UNO_SERVICES=service.rdb
</pre>

Bootstrap arguments may get passed by an optional .ini/rc file. It is searched for this .ini/rc file beneath the executable. The .ini/rc file must have the same name as the executable, extended with an '.ini' for windows respectively an 'rc' for Unix. Any executable extension like '.bin' or '.exe' are stripped from the name:
<pre>
echo 'UNO_SERVICES=service.rdb' > myapprc
./myapp.bin
</pre>

The name of the .ini/rc file to use can be overwritten with the 'setIniFileName' function.

Bootstrap arguments may also get passed via environment variables:
<pre>
setenv UNO_SERVICES service.rdb
./myapp.bin
</pre>

===Naming Conventions for Names of Bootstrap Arguments===
Names may only include characters, that are allowed characters for environment variables. This excludes '.', ' ', ';', ':' and all non-ASCII characters. Names are case insensitive. The following build in variables give access to specific directories:
<pre>
SYSUSERCONFIG is mapped to osl_getConfigDir
SYSUSERHOME   is mapped to osl_getHomeDir
SYSBINDIR     is mapped to the directory of osl_getExecutableFile
ORIGIN        expands to directory of this .ini/rc file
_OS           expands to the operating systems name (e.g. Windows, Solaris, Linux)
_ARCH         expands to the hardware architecture (e.g. x86, SPARC, MIPS)
</pre>

===Range of Values for Bootstrap Arguments===
Values maybe arbitrary Unicode strings which have to be encoded using UTF8. A simple argument expansion is supported:
* Allow expansion of variables in the right side of assignments: 
<pre>MYVAR=hallo
MYMYVAR=${MYVAR}/test
The value of MYMYVAR is 'hallo/test'
</pre>
* Allow indirect expansion of variables through 'osl' profiles: 
<pre>KEYVALUE=${sversionrc:versions:StarOffice6.0}</pre>
The first part of the indirection is the file to use for expansion, the second part is the section and the third part is the key. After expansion the variable KEYVALUE has the value of the matching key of the sversionrc.

The special characters are:
* $ - introduces a macro name, which should become expanded
* \ - quotes the next character
* \uXXXX - allows the definition of an 16 bit character (Unicode)
* {} - group the characters of macro name or an indirection to an ini-file
* - or ; or / - delimiters, which differentiate macros, which are not grouped with {}

==Special Variables==
A special bootstrap argument is supported. This argument defines the name of the '.ini/rc' to use for finding bootstrap arguments. The name of the argument is:
<pre>
INIFILENAME
</pre>

This argument can only be used on the command line:
<pre>
./myapp -env:INIFILENAME=globalrc
</pre>

==Application Arguments==
Application arguments are like bootstrap arguments, except, that they are not specifiable via environment variables or ini-files. Application arguments have to be given on the command line and are more like former called command line arguments.

The following two functions give access to application arguments:
<code>[cpp]
oslProcessError SAL_CALL rtl_getAppCommandArg(sal_uInt32 nArg, rtl_uString **strCommandArg) 
sal_uInt32 SAL_CALL rtl_getAppCommandArgCount() 
</code>

The function "rtl_getAppCommandArg" also supports macro expansion as defined for bootstrap arguments.

==Uno Default Bootstrapping==
Several things are needed to bootstrap a UNO application, for example the services the application wants to utilize or the types of the services, if they are not compiled in. Even a mutable and persistent registry for holding application specific data is sometimes needed. (E.g. in case of OpenOffice.org/[[StarOffice]]). To bootstrap an UNO application an initial UNO-context is needed. A new function in cppuhelper is providing a default bootstrapped initial UNO-context.
Creating a Default Bootstrapped UNO-context

As already mentioned, a UNO application may need several data, which have to be provided by the application user. To ease the usage of the application, a new function in cppuhelper creates a default bootstrapped UNO-context:
<code>[cpp]
Reference<XComponentContext> SAL_CALL defaultBootstrap_InitialComponentContext() SAL_THROW((Exception));
</code>

This function is completely externable customizable by the following bootstrap arguments:
* UNO_TYPES: a space separated list of type rdb file urls: <pre>UNO_TYPES=file:///.../types1.rdb types2.rdb ... </pre>
* UNO_SERVICES: a space separated list of service rdb file urls <pre>UNO_SERVICES=local_services.rdb file:///.../global_services.rdb:... </pre>
* UNO_WRITERDB: a write registry <pre>UNO_WRITERDB=mypersistentdata.rdb</pre>

This, in conjunction with the rtl bootstrap argument passing possibility, should be sufficient to bootstrap any UNO application.

==Examples==
===Bootstrapping OpenOffice.org===
OpenOffice.org uses one file as types and as services rdb. It also uses a user dependent writable rdb, which should be located in the users configuration directory. An 'sofficerc' with defines the bootstrap arguments may look like this:
<pre>
ProductKey = StarOffice6.0
ConfigFile = ${SYSUSERCONFIG}/.sversionrc
ConfigDir = ${$ConfigFile:versions:${ProductKey}}

UNO_WRITERDB = $ConfigDir/user.rdb
UNO_TYPES=applicat.rdb
UNO_SERVICES=applicat.rdb
</pre>

===Bootstrapping OpenOffice.org Setup===
OpenOffice.org Setup only needs UNO because VCL needs uno. All currently needed types are compiled in (this may change with usage of UNO via OpenOffice.org Basic). So, only some services are needed, which become registered into a 'setup_services.rdb', which gets searched during startup.

===Bootstrapping the Uno Executable===
The Uno executable should have access to any type and any service. It must not use a default writable registry, because it is used in different contexts (as an application, as an daemon, ..). To simplify usage I suggest to just use a simple .ini/rc file for passing the bootstrap arguments:
<pre>
UNO_TYPES=../../rdbs/udkapi.rdb
UNO_SERVICES=../../rdbs/udkservices.rdb
</pre>


[[Category:Spec]]
[[Category:Uno]]
[[Category:Uno:Binary]]