# Running Knopflerfish

## Starting Knopflerfish

The Knopflerfish OSGi framework is distributed as an executable jar file and is started by running java on the framework.jar file in the osgi directory.

        > cd osgi
        > java -jar framework.jar

The framework can also be started by double-clicking on the framework.jar file from Finder/Explorer or similar tools, depending on operating system used.

The compact version of the framework is started the same way, but instead of framework.jar the framework_compact.jar file must be used, e.g.

        > cd osgi
        > java -jar framework_compact.jar

It is also possible to start Knopflerfish from the ant build environment. This is typically done when running the Knopflerfish test suite.

The SDK installation starts a default set of bundles, including the Knopflerfish OSGi Desktop bundle and other utilities.

The Knopflerfish framework can be further controlled by:

- Supplying command line options
- Creating xargs file
- Setting framework and system properties

For a complete description of all framework feature please refer to the framework bundle documentation .

## Knopflerfish command line options

To control the behavior of Knopflerfish OSGi command line options can be supplied. To get help on the framework options, run the framework with the help option.

        java -jar framework.jar -help

This prints a help screen (exact contents is version dependent).

    java -jar framework.jar -help
    Knopflerfish OSGi framework launcher, version 6.0.0.0001
    Copyright 2003-2013 Knopflerfish. All Rights Reserved.
    See http://www.knopflerfish.org for more information.

     Usage:  java [properties] org.knopflerfish.framework.Main [options]
          or java [properties] -jar framework.jar [options]
          or ./kf2 [options] [-- [properties]]  [--- [extra]] (*)

     Options:
       -exit          Exit the JVM process
       -help          Print this text and exit
       -version       Print version and exit
       -jvminfo       Print system and framework properties and exit
       -sleep SEC     Sleep a while before next command.
       -xargs file    Load more command line arguments from file, exit if file
                      cannot be loaded.
       --xargs file   Load more command line arguments from file, continue
                      if file cannot be loaded (but print error)

       -create        Create and initialize a new framework instance
                      after a shutdown. The default is to reuse the old
                      framework instance.
       -ff FF         Specify the name of the FrameworkFactory to use when
                      creating the framework instance.
       -init          Start an empty platform (i.e., clear old presistent data).
       -launch        Launch framework (i.e., start it).
       -shutdown mSEC Shutdown framework, timeout in milliseconds.

       -install URL   Install a bundle
       -istart URL    Install and start bundle according to activation policy.
       -start ID      Start bundle (according to its activation policy)
       -start_e ID    Start bundle eagerly (i.e., ignore its activation policy)
       -start_et ID   Start bundle eagerly and transiently
       -start_pt ID   Start bundle transiently according to policy
       -stop ID       Stop bundle
       -stop_t ID     Stop bundle transiently (i.e, non-persistent stop)
       -uninstall ID  Uninstall a bundle
       -update ID     Update a bundle

       -initlevel N   Set initial start level for installed bundles
       -startlevel N  Set the beginning start level of the Start Level service

     Extra: (Only applicable when using ./kf2)
       -java PATH	  Use this JVM (Default=java)

     The default directory used for storing bundle data is  "fwdir".

     (*) Fully R4 compatible, enables support for bootclasspath extension bundles.

     For extended help and list of all available system properties, see online
     documentation or visit:

     http://www.knopflerfish.org/releases/current/docs/bundledoc/framework/index.html

## xargs files

The xargs file are Knopflerfish command line options specified in a text file, typically ending in .xargs. This is a convenient method for specifying which bundles to start as well as setting framework properties.

The Knopflerfish SDK includes the following .xargs files by default

init.xargs
  Initial or bootstrap start. Also used as default if no other xargs argument is given. See also Initial start vs restart .

  Generated from template.xargs.in (only present in a full source file installation).

headless.xargs
  Initial or bootstrap start to use when running the JVM is running in headless mode. Same set of bundles as in init.xargs except that bundles requiring AWT has been commented out.

  Generated from template.xargs.in (only present in a full source file installation) with "$(AWT)" set to '#'.

minimal.xargs
  Starts the framework and a minimal set of bundles.
props.xargs
  One common xargs file that only set properties. Is used, or sourced, by other xargs files.
remote-init.xargs
  Initial and bootstrap start with bundles loaded from an HTTP URL from a release specific bundle repository, located on www.knopflerfish.org, instead of loading from a file URL from the installation.
init-tests.xargs
  xargs file for the Knopflerfish test suite. Normally invoked via an ant target.
test-restart1.xargs
  xargs file for the Knopflerfish test suite. Normally invoked via an ant target.
test-restart2.xargs
  xargs file for the Knopflerfish test suite. Normally invoked via an ant target.

## Framework and System Properties

The behavior of Knopflerfish can be further controlled by specifying framework and system properties that are either specified by OSGi or Knopflerfish specific. The framework and system properties are described in detail in the framework bundle documentation .

There is a default properties setting in the `props.xargs` file.