PROJECT FORTRESS SUBVERSION REPOSITORY--------------------------------------This README exists in the top-level directory of the Fortress project.Information about Fortress can be found at the following web site:http://projectfortress.sun.comIf you have Subversion installed, you can check out the Fortressrepository by going to the directory in which you want to check it outand issuing the following command:    svn checkouthttps://projectfortress.sun.com/svn/Community/trunk PFC(The name "PFC" merely specifies the name of the directory you wantto check the code into.  Feel free to substitute another directoryname if you prefer.)You'll now have a subdirectory named 'PFC'.  Go into thatdirectory and you'll see several subdirectories:Fortify: The Fortify tool for converting Fortress code into LaTeX,both interactively and in batch mode.  Scripts are provided forconveniently producing rendered Fortress code in LaTeX documents,for producing PDF "doc" files from Fortress source code, etc.  SeeFortify/fortify-doc.txt for more information.ProjectFortress: The Fortress interpreter.  You'll need to build theinterpreter by following the instructions below for setting up yourenvironment in order to have a complete Fortress installation.Emacs: A directory holding the Emacs Lisp file fortress-mode.el,which defines a Fortress mode for Emacs.  To use this file, loadit from your .emacs file with the following command:    (load (concat (getenv "FORTRESS_HOME")                  "/contrib/Emacs/fortress-mode.el"))    (push '("\\.fs[si]$" . fortress-mode) auto-mode-alist)If you wish to use the Fortify package to format Fortress source codeinto LaTeX, you should also add the following to your .emacs (for moreinformation about fortify, see Fortify/fortify-doc.txt):    (load (concat (getenv "FORTRESS_HOME")                  "/Fortify/fortify.el"))Vim: A directory containing vim script files for syntax highlighting.To enable syntax highlighting for fortress code copy the sub-directoriesunder Vim/ to your ~/.vim directory.  $ mkdir ~/.vim  $ cp -a Vim/ftdetect Vim/syntax Vim/ftplugin ~/.vim/.If your cp command does not accept the -a option then use -r  $ cp -r Vim/ftdetect Vim/syntax Vim/ftplugin ~/.vim/.You should also add the following line to your ~/.vimrc file  au BufNewFile,BufRead *.fsi,*.fss set ft=fortressSpecData: Machine-readable files used by the Fortress LanguageSpecification (e.g., a list of all reserved words).  Editors and othertools may also benefit from using these files.  Moreover, all examplesincluded in the language specification are included in the directorySpecData/examples.Specification: A directory containing a PDF of the Fortress LanguageSpecification, Version 1.0.Library: The home for all of the Fortress standard libraries.bin: Shell scripts for our various projects.  These are bash scripts;you will need an installation of Bash on your system to run them.  Tomake these scripts "auto-homing", script "forfoobar" begins with theline    FORTRESS_HOME=`${0%forfoobar}fortress_home`This replaces 'forfoobar' in whatever was used to invoke the scriptwith 'fortress_home', runs that command, and assigns its output toFORTRESS_HOME for the remainder of the scripts.  'fortress_home'determines the location of fortress_home if it is not otherwisespecified.  This command can also be used in your own build files;for example, if you include the fortify macros in a LaTeX file    \input{$FORTRESS_HOME/Fortify/fortify-macros}you might precede the latex command with    FORTRESS_HOME="`fortress_home`"It is also possible to set FORTRESS_HOME in your environment, butif you have multiple versions of Fortress installed this can causeconfusion and build problems.You will also see the following files:ant: A small bash script used for invoking the build.xml withspecific Ant options.  (This script defers to the script with thesame name in directory ProjectFortress.)build.xml: The interpreter build script, written in Ant.  (Thisscript defers to the script with the same name in the directoryProjectFortress.)fortress.properties: This file defines several environment variablesused by the internals of the Fortress interpreter.  (Normally, there isno reason to override the settings in this file.)SETTING UP YOUR ENVIRONMENT---------------------------We assume you are using an operating system with a Unix-style shell(for example, Solaris, Linux, Mac OS X, or Cygwin on Windows).  Youwill need to have access to the following:* J2SDK 1.6 or later.  Seehttp://java.sun.com/javase/downloads/index.jsp* Ant 1.6.5 or later.  Seehttp://ant.apache.org/bindownload.cgi* Bash version 2.5 or later, installed at /bin/bash.  Seehttp://www.gnu.org/software/bash/Assume FORTRESS_HOME points to the PFC directory you checked out.  OnUnix-like systems this should be a matter of using export or setenv.  Ifyou are using Cygwin, one user reports success with the followingcommand line for setting FORTRESS_HOME:  export FORTRESS_HOME=`cygpath -am cygwin/path/to/fortress/install/directory`e.g.:  export FORTRESS_HOME=`cygpath -am ${HOME}/tools/fortress`In your shell startup script, add $FORTRESS_HOME/bin to your path.The shell scripts in this directory are Bash scripts.  To run them,you must have Bash accessible in /bin/bash.Make sure the following environment variables are set in your startupscript:    JAVA_HOME    ANT_HOME(Although our scripts are sometimes able to guess the locations ofJAVA_HOME and ANT_HOME, it is preferred that you set them manually.)Once all of these environment variables are set, build the interpreterby going to the directory FORTRESS_HOME and typing the command:    ./ant clean compileIf that doesn't work, there's a bug in the interpreter; please issue abug report.Once you have built the interpreter, you can call it from any directory,on any Fortress file, simply by typing one of the following commands at acommand line:    fortress [walk] [-test] [-debug interpreter] somefile.fss arg...    fortress helpThe first time you run a Fortress program, the static checker iscalled on the given file and the results are stored in a cachedirectory (by default this cache is kept in default_repository/cachesin the root of your Fortress distribution).  No user-visible objectfile is generated.  A file with suffix .fsi should contain a single APIdefinition.  The name of the API should match the name of the file.Similarly, a file with the suffix .fss should contain a singlecomponent definition.  The name of the component should match the nameof the file.A command of the form "fortress walk somefile.fss" checks whether acached and up to date result of compiling the given file exists.  Ifso, it runs the cached file.  Otherwise, it processes the given fileand runs the result.  This command can be abbreviated as "fortresssomefile.fss".  If the optional flag -test is given, all testfunctions defined in the given file are run instead.  If the optionalflag "-debug interpreter" is given, stack traces from the underlyinginterpreter are displayed when errors are signaled.If all else fails, look at the script bin/fortress to see if your systemhas peculiarities (for example cygwin requires ; separators in theclasspath).USING ECLIPSE-------------There exists a .project file in the directory ${FORTRESS_HOME}.Import this project into Eclipse.There exists a file called ${FORTRESS_HOME}/DOTCLASSPATH inthe repository. Copy this file to ${FORTRESS_HOME}/.classpath.If you are using the Java 5.0 jdk under Windows or Linux, you will needto add an entry to ${JAVA_HOME}/lib/tools.jar to the classpath.Setting up Eclipse to follow the Fortress project coding styleconventions is a two-step process. The following instructions areknown to work on Eclipse 3.4, and should work on Eclipse 3.3 as well.These will change preferences for all your Eclipse projects.Open up Eclipse Preferences to start configuring your globalsettings. First select General --> Editors --> Text Editorsand make sure the checkbox is enabled for "Insert spaces for tabs".Second select Java --> Code Style --> Formatter and click on the "Edit..."button. Change the Tab policy to "Spaces only" and give the profile a newname (recommended name: "Spaces only").  Click "OK" and you are finished.DEMO PROGRAMS-------------The directory ProjectFortress/demos/ contains some demonstration Fortressprograms.  Among them are:buffons.fss: Buffon's needle.  Estimates pi using a Monte Carlosimulation.lutx.fss: Naive dense LU decomposition.  Demonstrates how to definenew subclasses of Array2.conjGrad.fss: Conjugate gradient, including the snapshot from the NASCG benchmark that you've seen in many Fortress talks.  Uses the Sparselibrary for sparse matrices and vectors.sudoku.fss: Solve a simple sudoku by elimination.  Includes atree-based set implementation.aStar.fss: Generic A* search, accompanied by a specific instance forsolving sudoku that cannot be solved by elimination alone.Lambda.fss: A simple interpreter for the lambda calculus that permitstop-level binding and reduces to both WNHF and NF.  If you're curioushow to parse text using the Fortress libraries, you should look here(it's presently far more painful than we'd like).TEST PROGRAMS-------------The directory ProjectFortress/tests/ contains some Fortress programsto test the interpreter.  Test programs that are supposed to fail(for example, storing a String into a ZZ32-typed mutable) have namesthat are prefixed with XXX.The directory ProjectFortress/static_tests/ contains some Fortressprograms to test the static end.  Test programs that are supposed tofail have names that are prefixed with XXX.  Test programs that aresupposed to pass static disambiguation then fail have names thatare prefixed with DXX.The directory ProjectFortress/parser_tests/ contains some Fortressprograms to test the parser.  Test programs that are supposed tofail to be parsed have names that are prefixed with XXX.The directory ProjectFortress/not_passing_yet/ contains some Fortressprograms that should pass, but do not.  For example, if we had a testfile containing an error that should be detected, but it isn't, thatwould be contained in ProjectFortress/not_passing_yet with a nameprefixed with XXX.  Test programs in this directory should passthe parser.COMPONENTS----------Fortress currently lacks a full-blown component system.  All the codein your Fortress program should reside in API and component file pairs.If you take a look at the Fortress programs in ProjectFortress/tests/,ProjectFortress/demos/, or SpecData/examples, you'll see that they havethe same overall structure:component MyComponent  exports Executable  ...  Your program here ...  run():() = ...endLANGUAGE FEATURES THAT ARE IMPLEMENTED--------------------------------------* Object and trait declarations, including polymorphic traits.  Constructor invocations must *always* provide the static arguments  explicitly.* Overloaded functions and ordinary methods.  Top-level overloaded  functions can be polymorphic.  Nested functions and methods must be  monomorphic.* Polymorphic top-level functions and methods, so long as the methods  are not overloaded.* Checking and inference of argument types to functions, methods, and  operators.  These checks use the dynamic types of the arguments.  Return types are NOT checked.  Inference of static parameters is not  complete yet; it is often necessary to provide static arguments  explicitly.  It is *always* necessary to do so in a constructor call  and in any situation where a static parameter occurs only in the result  and not in the arguments to a function.  For example, you must always  provide the array element type E and size n when invoking the  factory array1[\E,n\]().* Arrays of up to three dimensions.  Note that there isn't yet a  single overarching Array type.  For more details on the array types  and operations defined see below.  In particular, note that array  comprehensions are not yet implemented; the array types provide  functions to work around this lack.  Another caveat: due to a bug we  haven't fully understood, some (but not all) uses of the compact  notation T[n,m] for an array type cause the interpreter to fail.  Desugaring the code by hand to e.g. Array2[\T,0,n,0,m\] works around  this bug.* Array aggregates except singleton arrays.* Parallel tupling and argument evaluation.* Parallel for loops over simple ranges such as 0#n.* Sequential for loops over simple ranges.  The functional method seq()  and the equivalent function sequential() can be used to turn any  Generator into a SequentialGenerator.* While loops, typecase, if, etc.  Note that for parametric types  typecase isn't nearly as useful as you might think, since it cannot  bind type variables; we are working to address this shortcoming.* The "atomic" construct uses code based on the DSTM2 library.  Nested  transactions are flattened.  We use their obstruction free algorithm  with a simple lowest-thread-wins contention manager.  Reduction  variables in for loops are not yet implemented, so perform an  explicit atomic update or just use a reduction expression instead.* throw and catch expressions.* Generators.* at expressions.* spawn* also (multiple parallel blocks)LANGUAGE FEATURES THAT ARE NOT IMPLEMENTED------------------------------------------* Numerals with radix specifiers (which implies that some numerals may be  recognized as identifiers)* Unicode names* Dimensions and units* Static arguments: nat (using minus), int, bool, dimension, and unit* Modifiers* Keyword arguments* Where clauses* Coercion* Constraint solving for nat parameters* Reduction variables* Distributions* Any of the types which classify operator properties* Any of the bits and storage types* Non-RR64 floats* Integers other than ZZ32 and ZZ64* Use of ZZ64 for indexing (the JVM uses 32-bit indices)CHANGES SINCE FORTRESS LANGUAGE SPECIFICATION v.1.0 BETA--------------------------------------------------------* Fortress 1.0 is the first  release of the Fortress languageinterpreter is the first to be released in tandem with the languagespecification, available as open source and online at:http://projectfortress.sun.comEach example in the specification is automatically generated froma corresponding working Fortress program which is run by every test runof the interpreter.* To synchronize the specification with the implementation, it wasnecessary to temporarily drop the following features from the specification: - Static checks (including static overloading checks) - Static type inference - Qualified names (including aliases of imported APIs) - Getters and setters - Array comprehensions - Keyword parameters and keyword expressions - Most modifiers - Dimensions and units - Type aliases - Where clauses - Coercions - Distributions - Parallel nested transactions - Abstract function declarations - Tests and properties - Syntactic abstraction* Libraries have significantly changed.* Syntax and semantics of the following features have changed: - Tuple and functional arguments - Operator rules: associativity, precedence, fixity, and juxtaposition - Operator declaration - Extremum expression - Import statement - Multiple variable declaration - Typecase expression* The following features have been added to the language: - "native" modifier - Operator associativity - Explicit static arguments to big operator applications* The following features have been eliminated from the language: - Identifier parameters - Explicit self parameters of dotted methods - Empty extends clauses - Local operator declarations - Shorthands for Set, List, and Map types - Tuple type encompassing all tuple types* Significantly more examples have been added.THE DEFAULT LIBRARIES---------------------The components ProjectFortress/LibraryBuiltin/FortressBuiltin.fsi,ProjectFortress/LibraryBiltin/NativeSimpleTypes.fss andLibrary/FortressLibrary.fss are imported implicitly whenever anyFortress program is run.BUILT-IN TYPES--------------There are a bunch of types that are defined internally by the Fortressinterpreter.  With the exception of Any, these cannot be overridden.The built-in types are found inProjectFortress/LibraryBuiltin/FortressBuiltin.fsi andNativeSimpleTypes.fsi; documentation for the released version of theselibraries can be found in the accompanying specification release.Most built-in types do not have any methods.  Note that the typesfound in FortressBuiltin do not have methods.Tuple and arrow types are always built in, and cannot be overridden inany way.Note that there isn't (yet) a trait Object!  Eventually user-writtentrait and object declarations will extend Object by default; right now,they instead extend Any by default.  We plan to migrate to a newinfrastructure for primitive objects (based on the one used forBoolean in NativeSimpleTypes) at which point we will remedy thissituation.Meanwhile, operations on the primitive types in FortressBuiltin can befound in Library/FortressLibrary.fsi; again these primitive aredocumented in the specification as well.  Note in particular that inthe absence of coercion, you may occasionally need to make use of widenand narrow to convert between ZZ32 and ZZ64.LIBRARY HIGH POINTS-------------------Your best guide to library functionality is the library code itself;this can be found in Library/ and in ProjectFortress/LibraryBuiltin.The APIs for these libraries can also be found in the languagespecification (note, though, that if you downloaded the latest versionof the Fortress implementation then the two may differ).  This sectionprovides an overview of things you may not immediately realize arethere.Juxtaposition of strings means string append.  You may alsofind the BIG STRING operation (that concatenates strings) useful.Several functions attempt to convert data of type Any to a string.These include print(), println(), assert(), and juxtaposition of Anywith a string.  Right now, the FortressBuiltin types are printed usinginternal magic, and object types are printed using the toStringmethod.  The consequence of this is that you will see a runtime errorif you attempt to print an object without first defining a toStringmethod.In the absence of array comprehensions, there are several ways tocreate and initialize an array (in these examples a 1-D array, but the2- and 3-D arrays work the same way):The simplest is to use an aggregate expression (this seems to fail attop level in your program, which is a known bug):    z : ZZ32[3] = [1 2 3]If you know the size statically (it is a static parameter to yourfunction, or is fixed at compile time):    a : T[size] = array1[\T,size\]()  (* lower bound 0 *)    a[i] := f(i),  i <- a.bounds()or:    a : T[size] = array1[\T,size\](initialValue)or:    a : T[size] = array1[\T,size\](fn (index:ZZ32) => ...)If you are computing the size at run time:    a = array[\T\](size)    a[i] := f(i),  i <- a.bounds()or:    a = array[\T\](size).fill(initialValue)or:    a = array[\T\](size).fill(fn (index:ZZ32) => ...)At the moment, to create a non-0-indexed array you need to create acorrectly-sized 0-indexed array as described above, then use theshift(newlower) method to shift the lower index.  Thus, to create annxn 1-indexed array you can do something like this:    a = array2[\T,n,n\]().shift(1,1)The replicate[\T\]() method on arrays is a little unintuitive atfirst.  It creates a fresh array whose element type is T but whosebounds are the same as the bounds of the array being replicated.  Whendata distribution is fully implemented, it should respect that as well.It is a bit like saying array[\T\](a.bounds().upper()) for 0-indexedarrays but is slightly more graceful and deals well with non-0-indexedarrays.You can convert any array to use 0 indexing simply by indexing it withan empty range:    a[:] or a[#]  ==>  a, only 0-indexed.Any operation that yields a subarray of an underlying array sharesstructure.  If you want a fresh copy of the data, use the copy() method.To assign the contents of array a to array b, you can use:    a.assign(b)if a is freshly allocated.  The following should work all the time:    a[:] := b[:]Right now type-level ranges don't really exist, so if you want tooperate on subarrays with statically type-checked bounds, you'll needto work with the subarray method:    subarray[\nat b, nat s, nat o\]():Array1[\T, b, s\]This returns a structure-sharing subarray with base b and size sstarting from offset o in the current array.The special factory functions vector and matrix are restricted to numericargument types and static dimensionality:    x' : ZZ64[1000] = vector[\ZZ64,1000\](17)At the moment, any Array1 or Array2 whose element type extends Numberis considered to be a valid vector or matrix respectively (this willeventually be accomplished by coercion, and vectors will be a distincttype).  Note that the t() method on matrices is transposition, andwill eventually be replaced by opr ()^T.GENERATORS, REDUCTIONS, and COMPREHENSIONS------------------------------------------Defining new generators is discussed in detail in the Fortresslanguage specification, but if you're trying it yourself for the firsttime, you may find it instructive to browse the source code of the libraries.DEFINING NEW PRIMITIVE FUNCTIONS--------------------------------It is relatively easy to add new primitive functions to Fortress.  Todo this, you simply invoke the builtinPrimitive function with the nameof a loadable Java class which extends glue.NativeApp.  Usefulsubclasses are NativeFn1 and NativeFn2, and any of the classes inglue.prim (particularly the classes in glue.prim.Util).  Here's asample native binding, which defines the floor operator which returnsan integer:    opr |\a:RR64/|:ZZ64 = builtinPrimitive("glue.prim.Float$IFloor")You should *not* mention the type parameter to builtinPrimitive wheninvoking it; doing so will confuse the interpreter.  Note also thatthe interpreter requires that you declare appropriate argument andreturn types for your native functions as shown above.  If you give anincorrect type declaration on the Fortress side, you'll getnon-user-friendly error messages when the Java code is run.DEFINING NEW PRIMITIVE CLASSES------------------------------To define a new primitive class, you will need to write a nativecomponent.  Examples of these can be found in Library; anything thatstarts with "native component" is a native component.  Here's thefirst few lines of File.fss:native component Fileimport FileSupport.{...}export Fileprivate language="java"private package="com.sun.fortress.interpreter.glue.prim"object FileReadStream(filename:String)        extends { ReadStream, FileStream}    getter fileName():String =      builtinPrimitive(        "com.sun.fortress.interpreter.glue.prim.FileReadStream$fileName")    ....Note that we import a non-native component that defines traitsmentioned in the extends clause.  The first two bindings must belanguage and package in that order; right now only language="java" issupported, and the package is where the backing class will be found.In com.sun.fortress.interpreter.glue.prim.FileReadStream defines thecorresponding backing data type.  Note that FileReadStream extendsConstructor, and defines an inner class that extends FOrdinaryObjectthat represents the actual values that get passed around at run time.The methods must extend NativeMethod, but are otherwise referencedusing builtinPrimitive just as for top-level functions.A native class can contain a mix of native and non-native methodcode.  Note, however, that the namespace in which a native object isdefined is slightly odd from the perspective of library namevisibility.  For this reason, some primitive classes extend a parenttrait (defined in a non-native component) that contains most of theirnon-native functionality and that has full access to the libraries.For example, FileStream provides a number of generator definitionsthat are inherited by FileReadStream.