The application structure is customizable via the standard mappings, which is described in the Universal Plugin Section.
Application and runtime configuration¶
There are generally two types of configurations:
- Configuring the JVM and the process
- Configuring the application itself
You have two options to define your runtime and application configurations.
Configuration file¶
The start scripts provided by the BatStartScriptPlugin
and BashStartScriptPlugin
can both load an external
configuration file during execution. You can define the configuration file location for both with these two settings.
bashScriptConfigLocation
The location of the bash script on the target system.
Default
${app_home}/../conf/application.ini
batScriptConfigLocation
The location of the bat script on the target system.
Default
%APP_HOME%\conf\application.ini
The configuration path is the path on the target system. This means that native-packager needs to process this path to create a valid ``universal:mapping``s entry.
${app_home}/../
is removed%APP_HOME%
is removed and\
is being replaced with/
This means you can either
- Create a configuration path relative to the application directory (recommended)
- Create an absolute path that has to match your target and build system
Example
// configure two different files for bash and bat
bashScriptConfigLocation := Some("${app_home}/../conf/jvmopts-bash")
batScriptConfigLocation := Some("%APP_HOME%\\conf\\jvmopts-bat")
Now we know how to configure the location of our configuration file. The next step is to learn how to provide content for the configuration file.
Via build.sbt¶
You can specify your options via the build.sbt
.
javaOptions in Universal ++= Seq(
// -J params will be added as jvm parameters
"-J-Xmx64m",
"-J-Xms64m",
// others will be added as app parameters
"-Dproperty=true",
"-port=8080",
// you can access any build setting/task here
s"-version=${version.value}"
)
For the -X
settings you need to add a suffix -J
so the start script will
recognize these as vm config parameters.
When you use the javaOptions in Universal
sbt-native-packager will generate configuration files
if you haven’t set the batScriptConfigLocation
and/or bashScriptConfigLocation
to None
.
Via Application.ini¶
The second option is to create src/universal/conf/application.ini
with the following template
# Setting -X directly (-J is stripped)
# -J-X
-J-Xmx1024
# Add additional jvm parameters
-Dkey=val
# Turn on JVM debugging, open at the given port
# -jvm-debug <port>
# Don't run the java version check
# -no-version-check
# enabling debug and sending -d as app argument
# the '--' prevents app-parameter swallowing when
# using a reserved parameter. See #184
# -d -- -d
The file will be installed to ${app_home}/conf/application.ini
and read from there
by the startscript. You can use #
for comments and new lines as you like. This file
currently doesn’t has any variable substitution. We recommend using the build.sbt
if
you need any information from your build.
The configuration file for bash scripts takes arguments for the BASH file on each line,
and allows comments which start with the #
character. Essentially, this provides
a set of default arguments when calling the script.
By default, any file in the src/universal
directory is packaged. This is a convenient
way to include things like licenses, and readmes.
If you don’t like application.ini
as a name, you can change this in the build.sbt
.
The default configuration looks like this
bashScriptConfigLocation := Some("${app_home}/../conf/application.ini")
batScriptConfigLocation := Some("%APP_HOME%\\conf\\application.ini")
Add code to the start scripts¶
The second option is to add code to the generated start scripts via these settings.
bashScriptExtraDefines
- A list of extra definitions that should be written to the bash file template.
batScriptExtraDefines
- A list of extra definitions that should be written to the bat file template.
BashScript defines¶
The bash script accepts extra commands via bashScriptExtraDefines
. Generally you can add arbitrary
bash commands here, but for configurations you have two methods to add jvm and app parameters.
// add jvm parameter for typesafe config
bashScriptExtraDefines += """addJava "-Dconfig.file=${app_home}/../conf/app.config""""
// add application parameter
bashScriptExtraDefines += """addApp "--port=8080""""
Syntax
${{template_declares}}
- Will be replaced with a series of
declare <var>
lines based on thebashScriptDefines
key. These variables are predefined: *app_mainclass
- The main class entry point for the application. *app_classpath
- The complete classpath for the application (in order).
BatScript defines¶
The Windows batch script accepts extra commands via batScriptExtraDefines
. It offers
two methods to add jvm and app parameters using similar syntax to the BASH script.
// add jvm parameter for typesafe config
batScriptExtraDefines += """call :add_java "-Dconfig.file=%APP_HOME%\conf\app.config""""
// add application parameter
batScriptExtraDefines += """call :add_app "--port=8080""""
Syntax
@@APP_ENV_NAME@@
will be replaced with the script friendly name of your package.
@@APP_NAME@@
will be replaced with user friendly name of your package.
@APP_DEFINES@@
will be replaced with a set of variable definitions, likeAPP_MAIN_CLASS
,APP_MAIN_CLASS
.
Start script customizations¶
While the native packager tries to provide robust BASH/BAT scripts for your applications, they may not always be enough. The native packager provides a mechanism where the template used to create each script can be customized or directly overridden.
Bash and Bat script extra defines¶
For the bat and bash script are separated settings available to add arbitrary code to the start script. See BashScript defines and BatScript defines for details.
The bashScriptExtraDefines
sequence allows you to add new lines to the default bash script used to start the
application. This is useful when you need a setting which isn’t mean for the command-line parameter list passed to the
java process. The lines added to bashScriptExtraDefines
are placed near the end of the script and have access to a
number of utility bash functions (e.g. addJava
, addApp
, addResidual
, addDebugger
). You can add lines to
this script as we did for the Typesafe config file above. For more complex scripts you can also inject a separate file
managed in your source tree or resource directory:
bashScriptExtraDefines ++= IO.readLines(baseDirectory.value / "scripts" / "extra.sh")
This will add the contents of /scripts/extra.sh
in the resource directory to the bash script. Note you should always
concatenate lines to bashScriptExtraDefines
as other stages in the pipeline may be include lines to the
start-script.
Overriding Templates (Bash/Bat)¶
Warning
Replacing the default templates should really only be done if:
- There is a bug in one of the script templates you need to workaround
- There is a deficiency in the features of one of the templates you need to fix.
In general, the templates are intended to provide enough utility that customization is only necessary for truly custom scripts.
In order to override full templates, like the default bash script, you can create a file in
src/templates/bash-template
. Alternatively, you can use a different file location by setting
bashScriptTemplateLocation
. There are
Similarly the windows BAT template can be overridden by placing a new template in src/templates/bat-template
.
You can also use a different file location by setting batScriptTemplateLocation
.