[Swift-commit] r7417 - trunk/docs/designs

[davidk at ci.uchicago.edu]

Author: davidk
Date: 2013-12-13 09:21:34 -0600 (Fri, 13 Dec 2013)
New Revision: 7417

Modified:
   trunk/docs/designs/swiftrun.txt
Log:
Some updates to config doc -
Explain some new files in the run directory
Document -properties and $RUNDIRECTORY
Better explanation of when to use app wildcards vs defining all apps


Modified: trunk/docs/designs/swiftrun.txt
===================================================================
--- trunk/docs/designs/swiftrun.txt	2013-12-11 23:13:46 UTC (rev 7416)
+++ trunk/docs/designs/swiftrun.txt	2013-12-13 15:21:34 UTC (rev 7417)
@@ -122,6 +122,8 @@
 2. $SWIFT_SITE_CONF/swift.properties - used for defining site templates.
 3. $HOME/.swift/swift.properties
 4. swift.properties in your current directory.
+5. Any property file you point to with the command line argument "-properties
+<file>"
 
 Settings get read in this order. Definitions in the later files will override
 any previous definitions. For example, if you have execution.retries=10 in
@@ -179,13 +181,13 @@
 The run directories can be useful for debugging. They contain:
 .Run directory contents
 |======================
+|apps     |An apps generated from swift.properties
+|cf       |A configuration file generated from swift.properties
 |runNNN.log|The log file generated during the Swift run
-|*.d       |Debug directory containing info logs generated during app
-executions. This will be moved to the runNNN directory after execution has
-completed.
+|scriptname-runNNN.d|Debug directory containing wrapper logs
+|scripts|Directory that contains scheduler scripts used for that run
 |sites.xml|A sites.xml generated from swift.properties
-|apps     |An apps generated from swift.properties
-|cf       |A configuration file generated from swift.properties
+|swift.out|The standard out and standard error generated by Swift
 |======================
 
 Using site templates
@@ -346,20 +348,21 @@
 
 App definitions
 ~~~~~~~~~~~~~~~
-Swift 0.95 introduces app wildcards. This new configuration mechanism will
-take advantage of that and use wildcards first by default. This means that, as
-long as an application is specified in your PATH, you will not need to supply
-the path.
+In 0.95, applications wildcards will be used by default. This means that 
+$PATH will be searched and pathnames to application do not have to be defined.
 
-However, in the case where you have multiple sites defined, and you want
-control over where things run, you may still have a need to define this. In
-this scenario, you will can define apps in swift.properties with something
+In the case where you have multiple sites defined, and you want
+control over where things run, you will need to define the location of apps.
+In this scenario, you will can define apps in swift.properties with something
 like this:
 
 -----
 app.westmere.cat=/bin/cat
 -----
 
+When an app is defined in swift.properties for any site you are running on,
+wildcards will be disabled, and all apps you want to use must be defined.
+
 General Swift properties
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Swift properties can be used in the new swift.properties file with no changes.
@@ -373,3 +376,22 @@
 http://www.ci.uchicago.edu/swift/guides/trunk/userguide/userguide.html#_swift_configuration_properties[User
 Guide entry for Swift configuration properties].
 
+Using shell variables
+~~~~~~~~~~~~~~~~~~~~~
+Any value in swift.properties may contain environment variables. For example:
+
+-----
+workdirectory=/scratch/midway/$USER/work
+----
+
+Environment variables are expanded locally on the machine where you are running
+Swift.
+
+Swift will also define a variable called $RUNDIRECTORY that is the path to the 
+run directory Swift creates. In a case where you'd like your work directory
+to be in the runNNN directory, you may do something like this:
+
+-----
+workdirectory=$RUNDIRECTORY
+-----
+