<commit_before>
////
Swift/T guide, asciidoc format
http://www.mcs.anl.gov/exm/local/guides/stc.html
////

:toc:
:numbered:

////
Settings:
////
:miscellaneous.newline: \n

= Swift/T Guide
v0.6.1, July 2014

The Swift/Turbine Compiler (STC) allows you to write Swift programs
and run them using Turbine.

== Support

An overview of Swift/T may be found at the ExM project site:

https://sites.google.com/site/exmcomputing

The Swift/T user discussion mailing list is found here:

http://lists.mcs.anl.gov/mailman/listinfo/exm-user

== Installation
Writing and running Swift/Turbine programs requires multiple packages.
This section provides generic instructions for installing Swift/T
on a range of systems.  We first cover locating and/or installing
prerequisite software packages, then we cover building Swift/T
from a source package.

The link:turbine-sites.html[Turbine Sites Guide]
is a accompanying resource for configuration settings and preinstalled software
for specific systems.

=== Installation of Prerequisites

1. Install or locate MPI implementation (MPICH, OpenMPI, etc.)
+
** On compute clusters, an MPI will almost certainly be pre-installed
** Many operating systems provide packages with MPI implementations
  that are usable, but often outdated.
  E.g. the +mpich2+ package on Debian/Ubuntu.
** See http://www.mpich.org[MPICH Guides] for information on installing the
  latest version of MPICH.
** Other MPI implementations are <<Build_configuration, supported>> as well.
+
Swift/T attempts to use MPI 3.0 functionality by default.  If you
are using an MPI implementation that does not support the MPI 3.0 standard,
you must set +MPI_VERSION=2+ (if using the +exm-setup.zsh+ build process),
or provide the +--enable-mpi-2+ configure option (if using
the manual build process).
+
2. Install or locate Tcl 8.6.
+
* Tcl is available through the package manager on many systems.
   You may need to install an additional Tcl development package
   in addition to the standard tcl package,
   e.g. +tcl8.6+ plus +tcl8.6-dev+ on Debian/Ubuntu systems.
* Source distributions are available at the http://www.tcl.tk[Tcl web site]
+
3. Install or locate SWIG
+
* You can check if SWIG is installed by running +swig -version+
* SWIG is available through the package manager on many systems.
* Source distributions are available at
   the http://swig.org[SWIG web site]

=== Installation of Swift/T from Source

Once you have found all prerequisites, we can continue with building
Swift/T from source.

1. Obtain the Swift/T source package
+
----
wget http://www.mcs.anl.gov/exm/local/downloads/exm-0.5.0.tar.gz
----
+
Cf. http://www.mcs.anl.gov/exm/local/downloads/downloads.html[Swift/T Downloads]
for other packages
+
2. Unpack and enter package directory
+
----
tar xfz exm-trunk.tar.gz
cd exm-trunk
----
+
3. Edit the settings file: +exm-settings.sh+
+
At a minimum, you must set the install directory with +EXM_PREFIX+.
On a standard system, no further configuration may be needed.
In many cases, however, you will need to modify additional
configuration settings so that all prerequisites can
be correctly located and configured (see Section
<<Build_configuration, Build configuration>>).
+
A range of other settings are also available here:
enabling/disabling features, debug or optimized builds, etc.
+
TIP: Save your +exm-settings.sh+ when you download a new package
+
4. Run the setup script
+
----
./exm-setup.zsh
----
+
If +exm-setup.zsh+ does not succeed on your system, see Section
<<Build_configuration, Build configuration>> below.
+
TIP: if you want more control than +exm-setup.zsh+ provides, you can
    build Swift/T with the
    <<Manual_build_configuration, manual configure/make workflow>>.
+
5. Add Turbine and STC to your paths
+
----
PATH=${PATH}:/path/to/exm-install/turbine/bin
PATH=${PATH}:/path/to/exm-install/stc/bin
----

== Usage

Swift code is conventionally written in +\*.swift+ files.  Turbine
code is stored in Tcl files +*.tcl+.  After writing the Swift program
+program.swift+, run:
----
stc program.swift
----

This will compile the program to +program.tcl+.  A second, optional
argument may be given as an alternate output file name.

Then, to run the program, use Turbine:

----
turbine -n 4 program.tcl
----

See the <<Turbine,Turbine section>> for more information about
running the program.

[[stc_arguments]]
STC accepts the following arguments:

+-A _name_=_value_+:: Set a command-line argument at
compile-time. This may be found at runtime using the Swift
<<argv,argument processing>> library. This option enables these
arguments to be treated as compile-time constants for optimization.
+-D _macro_=_value_+:: Define a C preprocessor macro.
+-E+:: Just run the C preprocessor: do not compile the program.  The
output goes into the STC output file (the second file name argument).<commit_msg>Updates for 0.7.0<commit_after>
////
Swift/T guide, asciidoc format
http://www.mcs.anl.gov/exm/local/guides/stc.html
////

:toc:
:numbered:

////
Settings:
////
:miscellaneous.newline: \n

= Swift/T Guide
v0.7.0, November 2014

The Swift/Turbine Compiler (STC) allows you to write Swift programs
and run them using Turbine.

== Support

An overview of Swift/T may be found at the ExM project site:

https://sites.google.com/site/exmcomputing

The Swift/T user discussion mailing list is found here:

http://lists.mcs.anl.gov/mailman/listinfo/exm-user

== Installation
Writing and running Swift/Turbine programs requires multiple packages.
This section provides generic instructions for installing Swift/T
on a range of systems.  We first cover locating and/or installing
prerequisite software packages, then we cover building Swift/T
from a source package.

The link:turbine-sites.html[Turbine Sites Guide]
is a accompanying resource for configuration settings and preinstalled software
for specific systems.

=== Installation of Prerequisites

1. Install or locate MPI implementation (MPICH, OpenMPI, etc.)
+
** On compute clusters, an MPI will almost certainly be pre-installed
** Many operating systems provide packages with MPI implementations
  that are usable, but often outdated.
  E.g. the +mpich2+ package on Debian/Ubuntu.
** See http://www.mpich.org[MPICH Guides] for information on installing the
  latest version of MPICH.
** Other MPI implementations are <<Build_configuration, supported>> as well.
+
Swift/T attempts to use MPI 3.0 functionality by default.  If you
are using an MPI implementation that does not support the MPI 3.0 standard,
you must set +MPI_VERSION=2+ (if using the +exm-setup.zsh+ build process),
or provide the +--enable-mpi-2+ configure option (if using
the manual build process).
+
2. Install or locate Tcl 8.6.
+
* Tcl is available through the package manager on many systems.
   You may need to install an additional Tcl development package
   in addition to the standard tcl package,
   e.g. +tcl8.6+ plus +tcl8.6-dev+ on Debian/Ubuntu systems.
* Source distributions are available at the http://www.tcl.tk[Tcl web site]
+
3. Install or locate SWIG
+
* You can check if SWIG is installed by running +swig -version+
* SWIG is available through the package manager on many systems.
* Source distributions are available at
   the http://swig.org[SWIG web site]

=== Installation of Swift/T from Source

Once you have found all prerequisites, we can continue with building
Swift/T from source.

1. Obtain the Swift/T source package
+
----
wget http://www.swift-lang.org/Swift-T/downloads/exm-0.7.0.tar.gz
----
+
Cf. http://www.mcs.anl.gov/exm/local/downloads/downloads.html[Swift/T Downloads]
for other packages
+
2. Unpack and enter package directory
+
----
tar xfz exm-trunk.tar.gz
cd exm-trunk
----
+
3. Edit the settings file: +exm-settings.sh+
+
At a minimum, you must set the install directory with +EXM_PREFIX+.
On a standard system, no further configuration may be needed.
In many cases, however, you will need to modify additional
configuration settings so that all prerequisites can
be correctly located and configured (see Section
<<Build_configuration, Build configuration>>).
+
A range of other settings are also available here:
enabling/disabling features, debug or optimized builds, etc.
+
TIP: Save your +exm-settings.sh+ when you download a new package
+
4. Run the setup script
+
----
./exm-setup.zsh
----
+
If +exm-setup.zsh+ does not succeed on your system, see Section
<<Build_configuration, Build configuration>> below.
+
TIP: if you want more control than +exm-setup.zsh+ provides, you can
    build Swift/T with the
    <<Manual_build_configuration, manual configure/make workflow>>.
+
5. Add Turbine and STC to your paths
+
----
PATH=${PATH}:/path/to/exm-install/turbine/bin
PATH=${PATH}:/path/to/exm-install/stc/bin
----

== Usage

Swift code is conventionally written in +\*.swift+ files.  Turbine
code is stored in Tcl files with extension +*.tic+ (for Turbine
Intermediate Code).  After writing the Swift program
+program.swift+, run:
----
stc program.swift
----

This will compile the program to +program.tic+.  A second, optional
argument may be given as an alternate output file name.

Then, to run the program, use Turbine:

----
turbine -n 4 program.tcl
----

You may compile and run in one step with: 

----
swift-t -n 4 program.swift
----

In this case, +program.tic+ is created in a temporary file and then
deleted after execution.  

+swift-t+ accepts arguments for both STC and Turbine.
Provide +-h+ to any tool (+swift-t+, +stc+, +turbine+) to obtain help.

See the <<Turbine,Turbine section>> for more information about
running the program.

[[stc_arguments]]
STC accepts the following arguments:

+-A _name_=_value_+:: Set a command-line argument at
compile-time. This may be found at runtime using the Swift
<<argv,argument processing>> library. This option enables these
arguments to be treated as compile-time constants for optimization.
+-D _macro_=_value_+:: Define a C preprocessor macro.
+-E+:: Just run the C preprocessor: do not compile the program.  The
output goes into the STC output file (the second file name argument).
{'fraction_non_alphanumeric': 0.09638314785373608, 'fraction_numerical': 0.006756756756756757, 'mean_word_length': 3.9556868537666174, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 2, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4892131', 'n_tokens_mistral': 3153, 'n_tokens_neox': 2983, 'n_words': 1284}