Hashdot script headers and profiles are parsed as UTF-8. In normal usage, hashdot property values will be constrained to the ASCII subset, and thus compatible with other ASCII-compatible script encodings.
A script header block is defined as an initial contiguous sequence of all lines beginning with the '#' (or hashdot.header.comment). The first line not beginning with '#' terminates the header block. With this block, any lines beginning with '#.' will be parsed as hashdot property directives. All other lines within the header are interpreted as "regular" comments.
#!/usr/local/bin/hashdot # Comment #. property.name = value ## Comment #. property.other = "other value" ## End of Header (next line doesn't start with '#') puts "hello"
Support for script languages not supporting '#' as a line comment: If hashdot.header.comment is set to an alternative line comment string (ex: "//") then the initial hashbang line will be ignored, and lines beginning with this comment string followed by '.' will be interpreted as property directives.
Profiles are collections of property directives in *.hdp files under a profile directory specified at hashdot compile time. In a profile, lines starting with "#" are normal comments and property directives are specified without a leading "#." Example:
# Hashdot example profile property.name = value
Single values and strings:
#. x.y.z = constant_value #. x.y.z = "string value"
List values:
#. some.list = value1 value2 value3 #. another.list = mixed "string values" list
List addition:
#. some.list = first #. some.list += second ==> first second
Variable reference expansion:
#. prop.one = first
#. prop.two = ${prop.one}/second
==> first/second
#. prop.one = a b
#. prop.two = ${prop.one} c d
==> a b c d
Delayed/recursive reference expansion:
#. rprop := first ${cprop}
#. cprop = second
= rprop => first second
In the above example rprop is expanded at the end of reading all profiles and thus the final value of cprop is used. This is useful for allowing overrides in script headers or later profiles.
Properties are read from profiles and the script header in the following order.
Profiles are read at the point of reference and in the order referenced. Currently profiles may be referenced and thus read more than once. Profile authors must exercise care to avoid circular references.
Property values set with (=) or (+=) are expanded when first encountered. Property values set with (:=) are expanded only after all profiles and any script header have been read.
The following properties have special meaning when processed by hashdot.
A list of arguments prepended to the argument array passed to the hashdot.main method (before any script file and arguments passed by the user on the command line.)
Change the process working directory to specified path. This is provided since the working directory can not be set from Java, and is typically used in conjunction with the daemon profile. The java.class.path or hashdot.io_redirect.file values may be specified relative to the new working directory.
See profile "daemon.hdp". If set to value != "false", Hashdot will fork and setsid prior to launching the JVM.
Setting a property with this prefix sets the equivalent environment variable. For example:
#. hashdot.env.GEM_HOME = /opt/jruby/gems
Sets GEM_HOME to "/opt/jruby/gems" in the environment. Note: Currently variable references with this prefix do not provide access to environment variables, but only those previously set with a hashdot property. This features is intended as a workaround for cases where an interpreter has existing environment dependencies.
Set an alternative to the standard '#' used when scanning for the script header. For example, groovy and rhino (Javascript) profiles set this to "//" instead.
These properties control redirecting STDOUT and STDERR on startup. It is strongly encouraged to redirect to a file other than /dev/null when running as a daemon (See hashdot.daemonize). Consider that java level errors/crashes and "kill -QUIT" stack dumps will all go to STDERR. The full script log output may also be sent to this file via STDOUT/STDERR. The log may be rolled via an an external agent like logrotate using the standard "postrotate" HUP signal. These properties should typically be overridden in the specific daemon script.
Will redirect STDOUT/STDERR to the named file. When set in conjunction with hashdot.daemonize, a HUP signal handler will also be registered (after the JVM is loaded) to reopen the named file. This facilitates using external log rotating utilities like logrotate.
Unless this variable is set to "false" the file specified by hashdot.io_redirect.file will be opened for append.
The java class containing a static main method to call, with the script as its first argument. This property is required.
#. hashdot.main = com.gravitext.hashdot.TestMain
These properties control interpretation of arguments to identify a script file to read for Hashdot headers.
A list of flags with following value arguments that will not be interpreted as a script file name.
A list of flags that will cause hashdot to terminate looking for a script file.
Attempt to create, lock, and write the final process ID to the specified file name. It is permissible to specify a path relative to the current working directory of the hashdot process (after any hashdot.chdir).
Only one process will succeed in acquiring the exclusive advisory lock, which is guaranteed to be cleared when the process exits. Attempts to start a second process will result in a warning being written to stderr or the redirected file. Normal process exit (including SIGTERM, etc.) will also allow the process to unlink the PID file. Abnormal exit originating outside the JDK (for example, an external "kill -9") will result in the lock being cleared but the PID file remaining. Since the file is unlocked however, this does not prevent a new process from starting.
This option is typically used in conjunction with the daemon profile or hashdot.daemonize.
Load the specified values as properties. Each profile is read from compiled in profile directory, i.e. "jruby" is loaded from "/etc/hashdot/profiles/jruby.hdp". Profiles are imported in the order specified (including nested imports) and are implied += for purposes of passing the final hashdot.profile property to the JVM. Example:
#. hashdot.profile += shortlived
Set by hashdot to the absolute path of the script file, if identified. Note that the script file argument as passed to the script interpreter will still be relative, unless hashdot.chdir is also used.
Set by hashdot to the absolute path of the directory containing the script file, if identified. See java.class.path for potential usage.
Set by hashdot to the home directory as found in the password database (i.e.: /etc/passwd) for the real user of the current process.
Set by hashdot to the hashdot launcher version.
The dynamic library to load for the JVM. An absolute path should be used, which includes selection of the client or server VM. See profiles/default.hdp for platform specific examples.
All path values are prepended to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac OS X) before loading the JVM. Use of this property to resolve JVM libraries is deprecated in favor of using an absolute hashdot.vm.lib value.
Java VM options in flag format as per the java command line. See java tool docs for details. The "-server" option is actually achieved via hashdot.vm.lib and should not be included here. Note that the last setting of any equivalent option wins, thus appending to this property will function as an override. Example:
#. hashdot.vm.options = -Xmx500m -Xss1024k #. hashdot.vm.options += -Xmx1500m ==> -Xmx1500m -Xss1024k
Used to set the Java system class path (like the '-cp' java launcher argument.) Supports file name globs on values (* and ? wildcards). Values are joined with a ':' as per Java UNIX format. Examples:
#. java.class.path += /opt/myservice/lib/*.jar
#. java.class.path += ./lib
#. java.class.path += ${hashdot.script.dir}/../lib/*.jar
Notes:
If set in the environment, verbose debug logging is enabled to standard error.