-- |
--
-- This module contains no code.  Its purpose is to explain the
-- overall architecture of the code base, with links to the relevant
-- modules and definitions.  It is intended for people who intend to
-- hack on the compiler itself, not for those who just want to use its
-- public API as a library.  Most of what's here discusses the
-- compiler itself, but we'll also provide pointers for where to find
-- the code for the various other tools and subcommands.
--
-- Much of the documentation here is by referencing other modules that
-- contain more information.  Make sure to follow the links.  Also,
-- make sure to click the *source* links to study the actual code.
-- Many of the links are provided not because the exposed module API
-- is particularly interesting, but because their implementation is.
--
-- = Compiler
--
-- At a very high level, the Futhark compiler has a fairly
-- conventional architecture.  After reading and type-checking a
-- program, it is gradually transformed, passing through a variety of
-- different /intermediate representations/ (IRs), where the specifics
-- depend on which code generator is intended.  The final result is
-- then written to one or more files.  We can divide the compiler into
-- roughly three parts: frontend, middle-end [sic], and backend.
--
-- == Frontend
--
-- The frontend of the compiler is concerned with parsing the Futhark
-- source language, type-checking it, and transforming it to the core
-- IR used by the middle-end of the compiler.  The following modules
-- are of particular interest:
--
-- * "Language.Futhark.Syntax" contains the source language AST definition.
--
-- * "Language.Futhark.Parser" contains parsers for the source
--   language and various fragments.
--
-- * "Futhark.Compiler" and "Futhark.Compiler.Program" contains
--   functions for conveniently reading and type-checking an entire
--   Futhark source program, chasing down imports, and so on.
--
-- * "Language.Futhark.TypeChecker" is the type checker itself.
--
-- * /Internalisation/ of the source language to the core IR is in
--   "Futhark.Internalise".
--
-- == Middle-end
--
-- The compiler middle-end is based around /passes/ that are
-- essentially pure functions that accept a program as input and
-- produce a program as output.  A composition of such passes is
-- called a /pipeline/.  The various compiler backends (@futhark
-- opencl@, @futhark multicore@, etc) use different pipelines.  See
-- "Futhark.Pass" and (less importantly) "Futhark.Pipeline".  The
-- actual pipelines we use are in "Futhark.Passes".
--
-- The compiler front-end produces a core IR program that is then
-- processed by a pipeline in the middle-end.  The fundamental
-- structure of this IR is defined in "Futhark.IR.Syntax".  As
-- mentioned in that module, the IR supports multiple
-- /representations/.  The middle-end always starts with the program
-- in the SOACS representation ("Futhark.IR.SOACS"), which closely
-- resembles the kind of free-form nested parallelism that the source
-- language permits.  Depending on the specific compilation pipeline,
-- the program will eventually be transformed to various other
-- representations.  The output of the middle-end is always a core IR
-- program in some representation (probably not the same one that it
-- started with).
--
-- Many passes will involve constructing core IR AST fragments.  See
-- "Futhark.Construct" for advice and guidance on how to do that.
--
-- === Main representations
--
-- * "Futhark.IR.SOACS": the initial core representation of any
--   Futhark program.  This is the representation on which we perform
--   optimisations such as fusion, inlining, and a host of other
--   cleanup.
--
-- * "Futhark.IR.GPU": a representation where parallelism is expressed
--   with flat /segmented operations/, and a few other GPU-specific
--   operations are also supported.  The pass
--   "Futhark.Pass.ExtractKernels" transforms a
--   'Futhark.IR.SOACS.SOACS' program to a 'Futhark.IR.GPU.GPU'
--   program.
--
-- * "Futhark.IR.MC": a representation where parallelism is expressed
--   with flat /segmented operations/, and a few other multicore-specific
--   operations are also supported.  The pass
--   "Futhark.Pass.ExtractMulticore" transforms a
--   'Futhark.IR.SOACS.SOACS' program to a 'Futhark.IR.MC.MC'
--   program.
--
-- * "Futhark.IR.GPUMem": like 'Futhark.IR.GPU.GPU', but with memory
--   information.  See "Futhark.IR.Mem" for information on how we
--   represent memory in the Futhark compiler.  This representation is
--   produced by "Futhark.Pass.ExplicitAllocations.GPU"
--
-- * "Futhark.IR.MCMem": the multicore counterpart to
--   'Futhark.IR.GPUMem.GPUMem'.  Produced by
--   "Futhark.Pass.ExplicitAllocations.MC".
--
-- == Backend
--
-- The backend accepts a program in some core IR representation.
-- Currently this must always be a representation with memory
-- information (e.g. 'Futhark.IR.GPUMem.GPUMem').  It then translates
-- the program to the /imperative/ IR, which we call ImpCode.
--
-- * "Futhark.CodeGen.ImpCode": The main definition of ImpCode, which
--   is an extensible representation like the core IR.
--
-- * "Futhark.CodeGen.ImpCode.GPU": an example of ImpCode
--   extended/specialised to handle GPU operations (but at a high
--   level, before generating actual CUDA/OpenCL kernel code).
--
-- * "Futhark.CodeGen.ImpGen": a translator from core IR to ImpCode.
--   Heavily parameterised so that it can handle the various dialects
--   of both core IR and ImpCode that it must be expected to work
--   with.  In practice, when adding a new backend (or modifying an
--   existing one), you'll be working on more specialised modules such
--   as "Futhark.CodeGen.ImpGen.GPU".
--
-- Ultimately, ImpCode must then be translated to some /real/
-- executable language, which in our case means C or Python.
--
-- * "Futhark.CodeGen.Backends.GenericC": framework for translating
--   ImpCode to C.  Rather convoluted because it is used in a large
--   number of settings.  The module
--   "Futhark.CodeGen.Backends.SequentialC" shows perhaps the simplest
--   use of it.
--
-- * "Futhark.CodeGen.Backends.GenericPython": the generic Python code
--   generator (see "Futhark.CodeGen.Backends.SequentialPython" for a
--   usage example).
--
-- = Command line interface
--
-- The @futhark@ program dispatches to a Haskell-level main function
-- based on its first argument (the subcommand).  Some of these
-- subcommands are implemented as their own modules under the
-- @Futhark.CLI@ hierarchy.  Others, particularly the simplest ones,
-- are bundled together in "Futhark.CLI.Misc".
module Futhark () where