Bootstrap Arguments and Micro Deployment
|
Contents
- Abstract
Micro Deployment
Bootstrap Arguments
Application Arguments
Examples
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:
- configuration:
- needs a bootstraprc (bootstrap.ini) to find
- the appropriate user configuration (e.g. local,
- portal, remote, ...)
- currently a special file (bootstraprc) is used
- UNO:
- needs to find the appropriate rdb files to get the needed
- types and services (see uno default bootstrapping for a
- more detailled discussion)
- currently this has to be programmed by hand
- java:
- needs to know the java installation to use, this may include
-
- a shared library path and needed jar files
- currently a special file (javarc) is used
Different, but similar concepts are used (e.g. a file with an
entry which points to a special directory). First, i would like to
unify these concepts and to use one mechanism for bootstrapping. Second,
i also would like to be able to configure the bootstrapping via command
line arguments or via environment variables (which, for instance,
may be set by setsolar). And third, i want not only micro deploy applications
but also libraries/subsystems.
All the different mechanisms used to configure any subsystem have something
in common, which i would like to call MICRO DEPLOYMENT. Micro Deployment allows
an arbitrary component (application/library) to be configured at deployment time.
So that some deployment dependent parameters have no to be compiled in.
E.g. a UNO service becomes typically deploied as a shared library. Because it needs
some minimal configuration data to work properly, every application which uses the service
has to pass this minimal configuration to the service. Using Micro Deployment, this
burden vanishes. The installer can create a minimal configuration, which the service
will use during runtime. This Micro Deployment is not only usable by shared libraries, but also by
executables.
The Micro Deployment should be as flexible and as simple as possible. It is not designed
to do some complex stuff during startup. Its api decomposes into three parts:
- Accessing Deployment/Bootstrap arguments for executables
- Accessing Deployment/Bootstrap arguments for shared objects/shared libraries/subsystems
- Accessing simple command line arguments
A mechanism to allow differentiated access to bootstrap
arguments at the runtime library (RTL) level is needed.
Passing Bootstrap Arguments
Bootstrap arguments may get passed to an executable or library by
different 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 by inheritance
- parameters may get passed as default values for 'rtl_bootstrap_get' (see below)
Passing Bootstrap Arguments via Command Line
Bootstrap arguments passed via command line must have a special shape to be
distinguishable from other command line arguments:
- myapp.bin -env:UNO_SERVICES=service.rdb
Here, the bootstrap parameter "UNO_SERVICES" becomes passed as a command line
parameter.
Passing Bootstrap Arguments via .ini/rc Files
Bootstrap arguments may get passed by an optional .ini/rc file.
Using the static methods of the Bootstrap class an .ini/rc file
is searched beneath the executable. The .ini/rc file must have
the same name as the executable, extended with an '.ini' for
windows respectivly an 'rc' for unix. Any executable extension
like '.bin' or '.exe' is stripped from the name:
- echo 'UNO_SERVICES=service.rdb'
> myapprc
./myapp.bin
The name of the .ini/rc file to use can be overwritten with the
'setIniFileName' function.
It is also possible to use a custom .ini/rc file name. Particulary when
using micro deployment for shared libraries, this makes sence.
- echo 'UNO_SERVICES=service.rdb'
> mylibrc
./an-app-using-mylib.so.bin
Passing Bootstrap via Inheritance
Bootstrap arguments may get inherited from an executable rc.
E.g. when using custom rc file for libraries, this custom
rc inherits the bootstrap variables from the executable rc
file.
Passing Bootstrap Arguments via Environment Variables
Bootstrap arguments may also get passed via environment
variables:
- setenv UNO_SERVICES service.rdb
- ./myapp.bin
-
Accessing Bootstrap Arguments via the RTL (Runtime Library)
To access bootstrap arguments a c and a c++ api exists. I just give
some brief code examples how to use the c++ api. Please have a look
at the header files bootstrap.h and bootstrap.hxx in sal/inc/rtl for
the whole api.
Accessing an executable bootstrap argument:
int main() {
int result = 0;
OUString argValue;
if(Bootstrap::get(
OUString(RTL_CONSTASCII_USTRINGPARAM("aNeededParameter")),
argValue)) {
fprintf(stderr, "found the parameter, doing something...\n");
do_something();
}
else {
fprintf(stderr, "did not find the parameter, dying...\n");
result = -1;
}
return result;
}
Accessing a library bootstrap argument:
int aLibraryFunction() {
OUString libraryFileUrl;
Module::getModuleUrl((void *)aLibraryFunction, libraryFileUrl);
// cut the library extension
iniName = libraryFileUrl.copy(0,
libraryFileUrl.lastIndexOf((sal_Unicode)'.'));
// add the rc file extension
iniName += OUString(RTL_CONSTASCII_USTRINGPARAM(SAL_CONFIGFILE("")));
Bootstrap bootstrap(iniName);
int result = 0;
OUString argValue;
if(bootstrap.getFrom(
OUString(RTL_CONSTASCII_USTRINGPARAM("aNeededParameter")),
argValue))
{
fprintf(stderr, "found the parameter, doing something...\n");
do_something();
}
else {
fprintf(stderr, "did not find the parameter, dying...\n");
result = -1;
}
return result;
}
Miscellaneous
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.
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:
MYVAR=hallo
MYMYVAR=${MYVAR}/test
The value of MYMYVAR is 'hallo/test'
-
Allow indirect expansion of variables through 'osl' profiles:
KEYVALUE=${sversionrc:versions:StarOffice6.0}
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 / - delimeters, which differentiate macros, which are not grouped with {}
Special Variables
Two build in
variables give access to a users configuration respectivly
to a
users home directory:
-
SYSUSERCONFIG is mapped to osl_getConfigDir
SYSUSERHOME is
mapped to osl_getHomeDir
A special bootstrap argument is supported. This argument
defines the name of the '.ini/rc' to use for finding bootstrap
arguments for executables. The name of the argument is:
- INIFILENAME
This argument can only be used on the command line:
- ./myapp -env:INIFILENAME=globalrc
-
Application arguments are like bootstrap arguments, except, that
they are not specifyable 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:
- oslProcessError SAL_CALL rtl_getAppCommandArg(sal_uInt32 nArg, rtl_uString **strCommandArg)
- sal_uInt32 SAL_CALL rtl_getAppCommandArgCount()
The function "rtl_getAppCommandArg" also supports macro expansion as defined
for bootstrap arguments.
Author:
KayRamme
($Date: 2002/01/03 15:01:42 $)
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.