docs/concierge-commandline.md

## Run Concierge from command line

When launching the Concierge .jar from command line, it takes an .xargs file as single argument. 
This file is used to configure the framework, set a couple of properties, and install or start
some bundles when first launched.

### .xargs file syntax

The .xargs file can contain both runtime properties for configuring the framework, as well as a set 
of framework commands. 

Properties are declared as `-Dkey=value`. Before launching, all `-D` properties are collected and
used to create a new framework instance. Within the .xargs file, one can also reference the declared property values by using `${key}`.

Next to properties, the .xargs file can also contain framework commands that are executed after the
framework is launched. These commands are executed in the order of occurence. Available commands are
`-install` to install a bundle, `-start` to start a bundle, `-istart` to install and start 
a bundle, etc.

Comments are preceded by a hash `#` sign.

### .xargs commands

`-install <bundle URL>` : installs a bundle from a given bundle URL  

`-start <bundle URL>` : starts a bundle that was previously installed from the given bundle URL

`-istart <bundle URL>` : install and starts a bundle from a given bundle URL  

`-all <file directory>` : install and start all .jar files in a given directory

`-initlevel <level>` : sets the startlevel that will be used for all next bundles to be installed 

`-skip` : skips the remainder of the .xargs file (handy for debugging)


### Sample .xargs files

The Concierge distribution download comes with sample .xargs files. For example, the following
.xargs file launches Concierge with some basic Apache Felix bundles providing declarative services, an event admin, configuration admin and metatype:

```
# xargs sample file to load some Felix bundles
# We will start the bundles in different start levels to show that capability

# uncomment to clean storage first
# -Dorg.osgi.framework.storage.clean=onFirstInit

# use a separate profile
-Dorg.eclipse.concierge.profile=felix

# repos to load bundles from
-Drepo=https://archive.apache.org/dist/felix

# load shell and logservice with start level 1
-initlevel 1
-istart bundles/org.eclipse.concierge.shell-5.0.0.*.jar
-istart ${repo}/org.apache.felix.log-1.0.1.jar

# start DS with start level 2
-initlevel 2
-istart ${repo}/org.apache.felix.scr-1.8.0.jar

# start other services with level 3
# First install (will use current start level 2), then start with level 3
-install ${repo}/org.apache.felix.eventadmin-1.4.2.jar
-install ${repo}/org.apache.felix.metatype-1.0.12.jar
-install ${repo}/org.apache.felix.configadmin-1.8.4.jar

-initlevel 3
-start ${repo}/org.apache.felix.eventadmin-1.4.2.jar
-start ${repo}/org.apache.felix.metatype-1.0.12.jar
-start ${repo}/org.apache.felix.configadmin-1.8.4.jar

# check different start levels in shell with command "startlevel <bundle-id>"
```
First, some properties are set using the `-Dkey=value` syntax, and next the bundles to 
start are declared.

The first two properties have to do with the Concierge storage directory. 
When Concierge launches, it automatically creates a storage directory to cache all the 
installed bundles. When launching again, it will first try to restore the previously cached
state. If you don't want this behavior, and want to start with a clean environment every
time, you can set the `org.osgi.framework.storage.clean` property to `onFirstInit`.
The `org.eclipse.concierge.profile` allows you to create a separate storage directory
for each profile.

The `repo` property is declared pointing to the Apache Felix repository, and is used later in the commands as `${repo}`.

Finally all bundles are installed and started with the `-istart` command or using `-install` and `-start` command. This can take both a web URL or a file system URL.

If you specify a `-initlevel <level>` all bundles installed or started later will start with the given start level.

[comment]: # (Website generated at Mon Nov 04 15:58:13 CET 2019 from commit a997b377af93142b33d25540115175fd71c65548)