[Swift-commit] r5017 - branches/release-0.93/docs/quickstart

Mon Aug 29 09:40:16 CDT 2011

Author: davidk
Date: 2011-08-29 09:40:16 -0500 (Mon, 29 Aug 2011)
New Revision: 5017

Modified:
   branches/release-0.93/docs/quickstart/quickstart.txt
Log:
Updates to quickstart guide


Modified: branches/release-0.93/docs/quickstart/quickstart.txt
===================================================================

--- branches/release-0.93/docs/quickstart/quickstart.txt	2011-08-29 04:27:45 UTC (rev 5016)
+++ branches/release-0.93/docs/quickstart/quickstart.txt	2011-08-29 14:40:16 UTC (rev 5017)
@@ -8,38 +8,29 @@
 and run the basic examples for Swift. If you are using a pre-installed 
 version of Swift, you can skip directly to the configuration section.
 
+Stable Releases vs. Development Releases
+----------------------------------------
+Stable releases of Swift have undergone more extensive testing than development releases.
+In general, they are more stable, have fewer bugs, and have been tested on a variety of
+systems.
+
+The development version of Swift is aimed at developers and testers. The development 
+code has the highest chance of containing buggy and untested code. If you need stability 
+please use the latest stable release. 
+
 Downloading a Swift Distribution
 --------------------------------
-There are three main ways of getting the Swift implementation: stable
-releases, nightly builds, and the source code repository.
+There are two main ways of getting the Swift implementation: binary
+releases and the source repository.
 
-
-Stable Releases
+Binary Releases
 ~~~~~~~~~~~~~~~
-Stable releases can be obtained from the Swift download page: Swift
-Downloads Page. Once you downloaded the package, please move to the 
-install section.
+For the majority of users, downloading and installing binary releases is recommended.
+Since Swift is written in Java, the binary packages will run on all supported platforms with 
+Java Runtime Environment 1.5 or greater. Binary releases can be obtained from the 
+http://www.ci.uchicago.edu/swift/downloads/index.php[Swift downloads page]. 
 
-
-Nightly Builds
-~~~~~~~~~~~~~~
-Swift builds and tests are being run every day. The Swift downloads page
-contains links to the latest build and test page. The nightly builds 
-reflect a development version of the Swift code and should not be used in
-production mode. After downloading a nightly build package, please
-continue to the install section.
-
-Source Repository
-~~~~~~~~~~~~~~~~~
-Details about accessing the Swift source repository together with build
-instructions are available on the Swift downloads page. Once
-built, the dist/swift-svn directory will contain a self-contained
-build which can be used in place or moved to a different location. You
-should then proceed to the configuration section.
-
-Installing a Swift Binary Package
----------------------------------
-Simply unpack the downloaded package (swift-<version>.tar.gz) into a
+Once downloaded, simply unpack the downloaded package (swift-<version>.tar.gz) into a
 directory of your choice:
 
 -----
@@ -48,91 +39,63 @@
 
 This will create a swift-<version> directory containing the build.
 
+Source Repository
+~~~~~~~~~~~~~~~~~
+The source code for Swift is available to developers who have an interest in contributing 
+new features. To build Swift from source code, you will need http://ant.apache.org/[Apache Ant]
+and http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java JDK]. Once
+built, the dist/swift-svn directory will contain your build.
 
-Configuring Swift
------------------
-This section describes configuration steps that need to be taken in
-order to get Swift running. Since all command line tools provided with
-Swift can be found in the |bin/| directory of the Swift distribution, it
-may be a good idea to add this directory to your |PATH| environment
-variable:
-
+To download and build Swift 0.93, follow these instructions:
 -----
-export PATH=/path/to/swift/bin:$PATH
+$ mkdir swift-0.93 
+$ cd swift-0.93 
+$ svn co https://cogkit.svn.sourceforge.net/svnroot/cogkit/branches/4.1.9/src/cog 
+$ cd cog/modules 
+$ svn co https://svn.ci.uchicago.edu/svn/vdl2/branches/release-0.93 swift 
+$ cd swift 
+$ ant redist
 -----
 
-Grid Security
-~~~~~~~~~~~~~
-For local execution of jobs, no grid security configuration is necessary.
+Setting your PATH
+-----------------
+Once Swift is installed, it is useful to add the swift binary to your PATH
+environment variable. To do this, first determine where the Swift bin
+directory is located. If you installed Swift from a binary release, it will
+be in the swift-0.93/bin directory where you installed it. If you followed
+the instructions above for installing Swift from a source repository, it
+will be located in swift-0.93/cog/modules/swift/dist/swift-svn/bin.
 
-However, when submitting jobs to a remote machine using Globus Toolkit
-services, Swift makes use of the Grid Security Infrastructure (GSI)
-at http://www.globus.org/toolkit/docs/4.0/security/key-index.html for
-authentication and authorization. The requirements for this are detailed
-in the following sections. Note that GSI is not required to be
-configured for local execution (which will usually be the case when
-first starting with Swift).
+Add the following line to the bottom of ~/.bashrc:
 
-User Certificate
-~~~~~~~~~~~~~~~~
-GSI requires a certificate/private key pair for authentication to Globus
-Toolkit services. The certificate and private key should be placed into 
-the ~/.globus/usercert.pem and ~/.globus/userkey.pem files, respectively.
+-----
+export PATH=$PATH:/full/path/to/swift
+-----
 
-
-Certificate Authorities Root Certificates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The Swift client libraries are generally required to authenticate the
-services to which they connect. This process requires the presence on
-the Swift submit site of the root certificates used to sign the host
-certificates of services used. These root certificates need to be
-installed in either (or both) the ~/.globus/certificates and
-/etc/grid-security/certificates directories. A package with the root
-certificates of the certificate authorities used in the 
-http://www.teragrid.org[TeraGrid] can be found
-http://security.teragrid.org/TG-CAs.html[here].
-
-Swift Properties
-~~~~~~~~~~~~~~~~
-A Swift properties file (named swift.properties) can be used to
-customize certain configuration aspects of Swift. A shared version of
-this file, etc/swift.properties in the installation directory can be
-used to provide installation-wide defaults. A per-user properties file,
-~/.swift/swift.properties can be used for user specific settings.
-Swift first loads the shared configuration file and, if present, the
-user configuration file. Any properties not explicitly set in the user
-configuration file will be inherited from the shared configuration file.
-Properties are specified in the following format:
-
+When you login, test this out by typing the command
 -----
-name=value
+$ which swift
 -----
 
-For details about the various properties Swift accepts, please take a
-look at the http://www.ci.uchicago.edu/swift/guides/userguide.php#properties[Swift Properties Section] 
-in the http://www.ci.uchicago.edu/swift/guides/userguide.php[Swift User Guide].
+This should point you to the path of the Swift binary.
 
-
 Running Swift Examples
 ----------------------
 The Swift examples can be found in the examples directory in the Swift
 distribution. The examples are written in the SwiftScript language, and 
-have |.swift| as a file extension.
+have .swift as a file extension.
 
-The Grid Security Infrastructure, which Swift uses, works with limited
-time certificates called proxies. These proxies can be generated from
-your user certificate and private key using one of grid-proxy-init or
-cog-proxy-init (the latter being a Java Swing interface to the former).
-
 Execution of a Swift workflow is done using the swift command, which
 takes the Swift workflow file name as an argument:
 
 -----
-cd examples/swift
-swift first.swift
+cd examples/tutorial
+swift hello.swift
 -----
 
-The
-http://www.ci.uchicago.edu/swift/guides/userguide.php#swiftcommand[Swift Command Options Section] 
-in the http://www.ci.uchicago.edu/swift/guides/userguide.php[Swift User Guide] contains details
-about the various options of swift.
+When you run this application, it should create a file called hello.txt.
+If this file gets created, you have successfully ran your first
+Swift script!
+
+More documentation on how to run Swift can be found at 
+http://www.ci.uchicago.edu/swift/docs/index.php,


