Table of Contents
In addition to all tasks, Schmant script programmers have access to an environment that contains support and utility classes as well as some built-in script functions. The built-in functions are script language-dependent and are discussed in the scripting language guides.
Information and error output from scripts and tasks are written to a
Report instance. Every execution thread has its own
instance which can be retrieved using the ReportManager
method getReport(). For some script languages,
the environment preparation script defines convenience functions for logging
from a script, see the scripting language guides. Scripts
written in other languages may use the Report methods directly, like
ReportManager.getReport().info("Info, info").
Just like any other logging API, output to a Report is categorized using a log level. Report uses five different levels.
Table 5.1. Report logging levels
| Level | Corresponding Java log Level | Description | Flags |
|---|---|---|---|
error | SEVERE | Errors that are fatal enough to abort the script execution. | -q -q |
warning | WARNING | Warning messages; messages that the script operator should see, but that are not fatal enough to stop the script execution. | -q |
info | INFO | Information messages, such as information about executing tasks. | |
debug | FINE | Debug messages that give more details about what tasks are doing. | -v |
trace | FINEST | Detailed messages that give a lot of information about what tasks are doing. | -v -v |
The "Flags" column in the table above contains the flags that is used for starting Schmant with the different log levels.
By default, the lowest level logged is info,
which means that debug and
trace messages are discarded.
The log level can be changed in several ways:
By using the -v or -q
flags one or several times when launching the build script. This sets the default log level
for all Report:s.
By calling ReportManager.getReport().setLevel(…)
directly from the script. The log level is set for the current thread's
Report and for all Report:s for threads that will subsequently be created
by the current thread.
By calling a task or task factory's setReportLevel
method. This changes the report level temporarily when running that task.
When a new execution thread is created, for instance by a TaskExecutor, the created thread inherits the log level from its parent thread.
There are different Report implementations. By default
StdoutReport is used. It logs output to standard out and
standard err. Use the -r argument when launching
Schmant to use another ReportFactory for creating other types
of Report:s.
The RedirectReportTF task can be used to redirect the output from a nested task to a file.
Schmant makes heavy use of EntityFS and build scripts do also have access to it. EntityFilter:s, EntityFS' utility classes and iterators are expressive tools for working with files and directories. See below for an example.
Example 5.1. Iterating over files and directories
A common trick when using files checked out from Subversion is to hide
all .svn directories using an
EntityFilter.
Example 5.2. Hiding .svn directories when creating
an EclipseWorkspace
Build scripts are in no way required to use EntityFS objects. One reason for not doing that is that Java's File:s are easier to use for someone that is not familiar with EntityFS. A script may also mix and match EntityFS entities and Java File:s. The next example shows how to move between the two worlds.
Example 5.3. From Java files to EntityFS and back again
All tasks are not EntityFS-aware, though. Tasks that use external libraries that don't use EntityFS or that launch external processes do not support EntityFS entities. For those tasks, EntityFS entities are translated to Java File:s in the argument interpretation process. Tasks that don't support EntityFS entities cannot use nice EntityFS features such as directory views or in-memory file systems. The task reference documentation for each Schmant task has information on whether it supports EntityFS entities or not.
EntityFS-aware tasks support locking file systems that prevent that parallel build threads accidentally modify the same files or directories. The file systems returned by SchmantFileSystems' methods are all locking, if that is not explicitly disabled.
For more information on using EntityFS with Schmant, see Appendix B, EntityFS cookbook.
The following variables are available to all running scripts:
props – PropertiesJava system properties and properties set using the
-p argument when launching Schmant.
args – List<String>Script arguments given after the script file on the command line.
org_schmant_scriptFile – EFileThe currently running script file (read only).
Environment variables are accessed through the
java.lang.System.getenv method.
Schmant scripts can use EntityFS Properties like in the example below.
Example 5.4. Using EntityFS property methods
Schmant has several utility classes with static methods which can be used by build scripts.
A singleton instance of the ArgumentInterpreter class is used by many tasks to interpret untyped arguments. See the section called “Interpreted arguments”. ArgumentInterpreter is seldom used directly by Schmant scripts.
This is not a utility class per se, but it
has the static listWithFilter method for
creating a list of DirectoryAndFilter objects from
a collection of directories and an EntityFilter. See for instance
the task reference documentation for RecursiveProcessTF for examples.
Utility methods for working with JRE and JDK installations.
Example 5.5. Using JdkUtil
Utilities for using project filters. See Chapter 8, Projects.
Holds a reference to each thread's Report object.
Utility methods for creating EntityFS FileSystem:s that a Schmant script may use. The created file systems have the SchmantReportLogAdapter log adapter set.
The SchmantFileSystems class also has the
makeFileBacked and
makeRandomlyAccessible for making
EFile entities File-backed and
FCRandomAccess:ible, respectively.
Various utility methods.
Utility methods for creating temporary files and directories. See the section called “Temporary files and directories”.
XML catalog that can be used for resolving entities when parsing or XSL transforming XML files. See the XsltTF task factory documentation for examples.
In addition to Schmant's own utility classes, many of EntityFS' utility classes may be useful. See Appendix B, EntityFS cookbook.
Build scripts often have to use temporary files for storing data that is being processed, or sometimes even entire temporary directory hierarchies for, for example, compiled classes before they are added to a Jar file.
The TempFileUtil class has a set of static methods
for creating temporary files and directories. Entities created using
TempFileUtil are automatically deleted when Schmant
exits (unless it was started with the -k
flag).
As long as the tasks that are used are EntityFS-aware, temporary directories may well be in a RAM file system. The SchmantFileSystems.createRamFileSystem() method can be used to create a RAM file system configured for using with a build script. See the section called “In-memory file systems”.
By default, (process) tasks that use temporary directories use the default temporary directory of their target's file system. TemporaryDirectoryConfigurable task factories can be configured with a custom temporary files directory – a RAM file system directory, for instance.
Just like for any other program, it sometimes makes sense to split a build script into several different files. This is especially true for larger and more complex build scripts. The mechanisms for including script files into other script files are script language-dependent and are discussed in the scripting language guides.