Jump to: navigation, search

Common headless flags (Buckminster)

Buckminster headless has a set of flags applicable to the basic entrypoint, rather than to an individual command. They essentially influence the context in which the commands run and/or provide a meta-way to customize the startup.

The available flags can be roughly divided into a couple of groups:

  • Workspace management
  • Logging
  • User interaction
  • JVM specialization

Below follows an introduction to what the various flags do. See the --help flag for more details at this point.

Workspace management

As Buckminster at its heart uses the Eclipse framework, this exhibits itself in a couple of ways. One of these ways is that an ingrained concept is to work with a 'workspace', just like the Eclipse IDE does.

As it happens, the location of this workspace must be set very early in the lifecycle of an Eclipse application, and this is thus the interface to it. The flag(s) are either '-W' or '---workspace' and should point to a directory (automatically created if not existing). By default, a workspace called 'workspace' will be used (created when first referenced) in the user's home directory.

Logging

Buckminster internally has a logging system. This is clearly visible when in the IDE (from the preferences pages). From the command line there are a number of flags to control logging behavior. A basic idea is that Buckminster goes to some lengths to trap writes to System.out/err as well as the Eclipse internal log, and to do so in a synchronous fashion with specific log writes. A full log from a run which mysteriously fails will help a great deal in isolating the problem in an 'after-the-fact' fashion.

Command line flags
flag explanation
-L

--log

The most basic of the logging flags - turn on logging directly to stdout.
--logtofile This turns on logging to a log file. Using '---appendtolog' will turn on append mode.
--[no]trapouttolog

--[no]traperrtolog
--[no]trapeclipselogtolog
--trapoutloggername
--traperrloggername
--trapeclipselogloggername

Turns on or off trapping of System.out/err, Eclipse log. Default, they are all turned on.
--logconfiguration Buckminster (currently) uses Log4J as its engine. This advanced capability can be used to customize the actual logging configuration used.
--nobootlog The boot process is somewhat convoluted so by default the launcher logs what it is doing and later provides this information to the finished application so it can be channeled to the 'real' log. This information is crucial to understand exactly how the app was started. Using this options turns this off logging off. Note that the '--boottrace' flag differs from this — tracing is always done straight to stdout and may be necessary to debug the boot (logging) itself...

User interaction

There are some aspects that touches on how the user sees the results etc of running commands.

Command line flags
flag explanation
--displaystacktrace This option can be given if the user desires a full stack trace printout in case of actual code problems — normally it just prints a less daunting problem report if that happens. Regular 'errors' (e.g. bad usage of flags or similar should obviously be reported to the user in a more understandable manner).
--[no]progress

--progressconfiguration

Ingrained into the Eclipse architecture is frequent use of an abstract 'progress monitor'. Normally, there are various implementations for this available when using the GUI — dialogs with progress bars etc. In a command line setting though, all we have to work with is essentially stdout. So, the Buckminster framework provides (at least one) progress monitor implementation that gives a credible representation on stdout. Which implementation is chosen is defined by the user and thus transparent to the individual commands. By default it's turned on using a default implementation. The configuration flag allows a user to switch implementations, and/or configure the selected progress monitor itself.

This is an extension point and new monitors can thus be added. Note that it is up to a command to actually use the implementations here - internally the command must request a monitor from 'the context'.

--tmpdir Occasionally, the framework and/or a command needs to use temporary files. This is just a convenient way for a user to express a desire to steer such tmp files to a specific location. It is up to a command to use this information.
--notrapctrlc By default, Buckminster attempts to trap Ctrl-C. This trapping can be turned off entirely with this flag. The reason for trapping Ctrl-C is that, since below the Eclipse framework may be active doing something to the workspace or other managed resource when Ctrl-C is pressed. Since Ctrl-C will by default simply interrupt the application and exit, this can occur such that the workspace is left in an inconsistent state. This is frequently less of a problem when using the IDE since a user has to knowingly kill the entire process. Instead, the Ctrl-C trap tries to send proper 'cancel' requests to known/active progress monitors which should cause the code using those monitors to cleanly exit. In case this still doesn't work, see --ctrlcforceexitcount for a way out.
--ctrlcforceexitcount In case an app doesn't cleanly exit, pressing Ctrl-C repeatedly will exit the VM anyway. This flag allows specifying the number of required Ctrl-C presses for this to happen. Defaults to 5.
--boottrace This is normally used for solving problems with the launcher but may be important to understand how a given sequence of JVM arguments are passed on — see below.

JVM specialization

Buckminster is a Java application, and thus needs a JVM. By default, Buckminster will be started assuming the regular operating system command 'java' works. There are two reasons why this may not be adequate: either the JVM selected by that command is not the one wanted, and/or the user wants to pass in flags intended for the JVM (e.g. manipulating the memory sizes).

Command line flags
flag explanation
--vm This can be used to specifically select a JVM.
--vmarg This can be used to send flags to the VM to run. This flag works a bit unusually in that it is important to use it in the correct sequence. Also, to minimize issues where command line escaping must be used, one --vmarg per actual argument must be used, and they will internally be reformatted to be actual flags to the JVM. To understand this process the --boottrace flag may be useful.
--forcenewvm If the launcher finds that it must start a new VM to accommodate the --vm --vmarg flags used, it will do so, otherwise it will attempt to run in the same VM as the launcher. If necessary a new VM can be forced, regardless.