[Doc] OpenCilk 1.0 RC2; plaintext-->markdown

INSTALLING.md

@@ -0,0 +1,63 @@
+## Instructions for building OpenCilk from source
+
+The prerelease version of OpenCilk is available as source code in three git
+repositories, plus this infrastructure facilities repository.  You will need 1.8
+GB of space for the source code (mostly LLVM) plus 3.5 GB of space to build
+(total 5.3 GB).  You will need a compiler capable of building LLVM.  Any
+compiler you are likely to have installed on a modern multicore system should
+work.  OpenCilk 1.0 only supports 64-bit x86 on Linux or Unix-like operating
+systems.
+
+### Obtaining the OpenCilk source code
+
+Clone the OpenCilk compiler, runtime, and productivity tool repositories.  The
+Cheetah runtime and OpenCilk tool repositories must be cloned into
+sub-directories of the OpenCilk project directory:
+
+    git clone -b opencilk/v1.0-rc2 --single-branch https://github.com/OpenCilk/opencilk-project
+    git clone -b opencilk/v1.0-rc2 https://github.com/OpenCilk/cheetah opencilk-project/cheetah
+    git clone -b opencilk/v1.0-rc2 https://github.com/OpenCilk/productivity-tools opencilk-project/cilktools
+
+Clone the OpenCilk infrastructure repository, which contains the OpenCilk build
+script:
+
+    git clone -b opencilk/v1.0-rc2 https://github.com/OpenCilk/infrastructure
+
+### Building OpenCilk
+
+Run the `infrastructure/tools/build` script with two or three arguments.  The
+1st argument is the absolute pathname to the `opencilk-project` repository
+directory.  The 2nd argument is the absolute pathname of a directory to build
+OpenCilk.  The 3rd argument, if present, tells the build system how many
+parallel jobs to run.  Default parallelism is equal to the number of logical
+cores, or 10 if the number of cores is not detected.
+
+For example:
+
+    # ...git clone as above...
+    infrastructure/tools/build $(pwd)/opencilk-project $(pwd)/build 60
+
+OpenCilk takes a few CPU-hours to build on a modern system --- less than 10
+minutes on a 24-core Ryzen with a fast disk.  It might take all day
+single-threaded on an older machine.
+
+To echo the OpenCilk build script call syntax, use the `--help` switch:
+
+    infrastructure/tools/build --help
+
+### Usage
+
+You can run the OpenCilk C compiler out of its build tree, adding `/bin/clang`
+to the build directory name.  Similarly, add `/bin/clang++` for the OpenCilk C++
+compiler.
+
+You must have a chip with Intel's Advanced Vector Instructions (AVX).  This
+includes Sandy Bridge and newer Intel processors (released starting in 2011), and
+Steamroller and newer AMD processors (released starting in 2014).
+
+On MacOSX, you will need an XCode or CommandLineTools installation to
+provide standard system libraries and header files for clang.  To run
+clang with those header files and libraries, invoke the clang binary
+with `xcrun`; for example:
+
+    xcrun $(pwd)/build/bin/clang

README.md

@@ -0,0 +1,84 @@
+## Welcome to OpenCilk!
+
+This repo contains infrastructure tools for building the OpenCilk 1.0 RC2
+compiler, runtime, and productivity tools.  Specifically, it includes scripts
+for building OpenCilk from source or downloading and installing a pre-built
+docker image of OpenCilk.
+
+### Supported systems
+
+OpenCilk 1.0 RC2 is targeted to experienced Cilk users running Unix/Linux on
+modern x86_64 processors (e.g., Haswell, Excavator, or newer).  The present
+version has been tested on the following operating systems:
+
+- Ubuntu 18.04 and 20.04
+  - including via the Windows Subsystem for Linux v2 (WSL2) on Windows 10
+- FreeBSD 12.1
+- Fedora 30
+- Mac OS X 10.15
+
+### Summary of OpenCilk features
+
+- The `cilk_spawn`, `cilk_sync`, and `cilk_for` keywords are enabled by using
+  the `-fopencilk` compiler flag and including `<cilk/cilk.h>`.
+- The compiler is based on [LLVM 10][llvm-10-doc] and supports the usual
+  [`clang`][clang-10-doc] options.
+- Both C and C++ are supported.
+- Prototype support for C++ exceptions is included.
+- Reducer hyperobjects are supported using the Intel Cilk Plus reducer library
+  --- i.e., the hyperobject headers from Intel Cilk Plus --- except that it is
+  not valid to reference the view of a C reducer after calling
+  `CILK_C_UNREGISTER_REDUCER`.
+- Cilksan instrumentation for determinacy-race detection is enabled by using the
+  `-fsanitize=cilk` compiler flag.
+- Cilkscale instrumentation for scalability analysis and profiling is enabled by
+  using the `-fcilktool=cilkscale` compiler flag.  Cilkscale offers an API for
+  analyzing user-specified code regions, which is made available by including
+  `<cilk/cilkscale.h>`, and includes facilities for benchmarking an application
+  on different numbers of parallel cores.
+
+OpenCilk 1.0 RC2 is largely compatible with Intel's latest release of Cilk
+Plus.  Unsupported features include:
+
+- Cilk Plus array slice notation.
+- Certain functions of the Cilk Plus API, such as `__cilkrts_set_param()`.
+
+[llvm-10-doc]:  https://releases.llvm.org/10.0.0/docs/index.html
+[clang-10-doc]: https://releases.llvm.org/10.0.0/tools/clang/docs/index.html
+
+### Useful links
+
+- Instructions for building OpenCilk from source:  
+  <https://github.com/OpenCilk/infrastructure/blob/release/INSTALLING.md>
+
+- Scripts for building a Docker image with OpenCilk:  
+  <https://github.com/OpenCilk/infrastructure/blob/release/docker>
+
+- Link to the OpenCilk infrastructure GitHub repo:  
+  <https://github.com/OpenCilk/infrastructure>
+
+- Some simple demo Cilk programs:  
+  <https://github.com/OpenCilk/tutorial>
+
+- Additional demo Cilk programs:  
+  <https://github.com/OpenCilk/applications>
+
+- OpenCilk website:  
+  <http://opencilk.org>
+
+### Contact
+
+Bug reports should be emailed to [[email protected]](mailto:[email protected]).
+Other queries and comments should be emailed to
+[[email protected]](mailto:[email protected]).
+
+### OpenCilk development team
+
+- Tao B. Schardl, MIT --- Director, Chief Architect
+- I-Ting Angelina Lee, WUSTL --- Director, Runtime Architect
+- John F. Carr, consultant --- Senior Programmer
+- Dorothy Curtis, MIT --- Project Manager
+- Charles E. Leiserson, MIT --- Executive Director
+- Alexandros-Stavros Iliopoulos, MIT, postdoc
+- Tim Kaler, MIT, postdoc
+- Grace Q. Yin, MIT, intern