Language

The Free and Open Productivity Suite
Released: Apache OpenOffice 4.1.15

Bootstrap Arguments and Micro Deployment

OpenOffice.org

Contents

Abstract
Micro Deployment
Bootstrap Arguments
Application Arguments

Abstract

While introducing a simple concept for UNO bootstrapping 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, etc.)
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 detailed 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

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.

Micro Deployment

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 do not have to be compiled in.

For example, a UNO service becomes typically deployed 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:

Bootstrap Arguments

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

Passing Bootstrap Arguments

Bootstrap arguments may be passed to an executable or library, in different ways:

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", is passed as a command line parameter.

Passing Bootstrap Arguments via .ini/rc Files

Bootstrap arguments may be 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 or 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. Particularly, when using micro deployment for shared libraries, this makes sense.

	echo 'UNO_SERVICES=service.rdb' > mylibrc
	./an-app-using-mylib.so.bin

Passing Bootstrap via Inheritance

Bootstrap arguments may be 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 be 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 of 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 allowable characters for environment variables. This excludes '.', ' ', ';', ':' and all non-ASCII characters. Names are case insensitive.

Range of Values for Bootstrap Arguments

Values may be arbitrary Unicode strings which have to be encoded using UTF8. A simple argument expansion is supported:

The special characters are:

Special Variables

There are some integral variables available:

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

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, the formerly 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: 2004/11/27 05:58:37 $)
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache, OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. The Apache feather logo is a trademark of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.