README.devel

===========================
Chapel developer's file map
===========================

The README and README.files files in this directory are intended for
the end-user whose directory and file structure differs somewhat from
what a developer would see in their git tree.  This file is meant to
provide similar information as README.files for developers, and to map
between the developer directory structure and the release directory
structure.

The following files/directories are ones that are the same and in the
same place for developers and end users:

./
  README           : the end user's main README
  README.files     : the end user's guide to the directory structure
  CHANGES          : the end user's list of changes since the previous release
  CONTRIBUTORS     : the end user's list of contributors to Chapel
  CONTRIBUTORS.devel : contributors to code base not distributed in the release
  COPYRIGHT        : the end user's copyright information for Chapel
  LICENSE          : the end user's licensing agreement for Chapel
  STATUS           : the end user's status description of a release
  Makefile         : the end user's top-level Makefile
  bin/                       : when the compiler is made it's put in this
    `printchplenv -compiler` :   directory structure for both developers
                             :      and end users
  lib/
    `printchplenv -runtime`  : same as bin, but for the runtime libraries
  make/            : Makefiles used to build compiler, runtime, generated code
    Makefile       : debugging Makefile -- prints some of the settings
    Makefile.base  : base Makefile to be included by all other Makefiles
    Makefile.platform : determines what platform we're making from
    Makefile.<platform> : platform-specific Makefile settings
    Makefile.gnu   : a generic set of GNU tools -- included by many of the above
    Makefile.generic     : generic Makefile used with unknown platforms
    Makefile.generic.gnu : ditto, but for GNU-oriented platforms
    Makefile.release : used by the gen_release script to add copyrights?
    Makefile.unknown  -- generates error message when platform isn't recognized
  modules/         : location of Chapel modules for developers and users
  tar/             : location of tar files generated by scripts
  util/            : a bunch of miscellaneous scripts; the end user's is
                     a subset of the developer's


The following files/directories in the release are based on those in
the git tree, but not exactly the same:

  compiler/ : a copyright-annotated (and possibly pruned) copy of the
              developer's version of this compiler sources directory

  doc/      : for the end user, this directory is built from a 
              combination of the developer's doc/release directory and
              some documents that are built and installed by the
              gen_release script.  For the developer, this directory
              is currently somewhat disorganized apart from the
              release/ subdirectory.

  examples/ : for the end user, this directory is taken wholesale
              from test/release/examples in the developer hierarchy
              (with outdated subdirectories pruned).

  man/ :      for the developer, this directory contains the sources
              for our man page as well as for the man page itself, built
              using "make man" from the top-level directory.  For
              users, this directory only contains the resulting man
              page structure.

  runtime/ : see compiler/ above


The following files/directories are for developers only:

  README.devel     : this file
  DIRS             : a developer's view of files/directories, similar to
                     README.files above; currently out of date, possibly
                     redundant with this file
  TAGS             : an emacs TAGS file created after every compile when
                     CHPL_DEVELOPER is set to true
  chapel.tar.gz    : when the util/gen_release is script, the release is
                     left in this file
  chapel-emacs.tar.gz : ditto for the util/gen_editors script
  chapel-vim.tar.gz   : "
  etc/             : miscellaneous stuff -- see the README/README.devel there
  log/             : this directory is created when using the -t compiler
                     option, and so often ends up in this location
  papers/          : LaTeX sources for various papers and publications
  spec/            : the LaTeX sources for the language specification
  test/            : the Chapel testing system in all its glory
  third-party/     : repository for code by others