--------------------------------------------------------------------------------
    Introduction
--------------------------------------------------------------------------------

    Makery is a build system that is:

    -   Lightweight.  Requires only a shell, GNU Make, and standard
        command-line tools.

    -   Modular.  Build functionality is implemented in modules, which can
        depend on one another.

    -   Multi-project.  Can build multiple projects with inter-project
        dependencies in a single invocation.


    Think of Makery as the solutions and projects from Visual Studio or Eclipse,
    but without the IDE, and with more convention-over-configuration.



--------------------------------------------------------------------------------
    Status
--------------------------------------------------------------------------------

    Makery is in an alpha state.  It is fully-functional but subject to
    frequent change.



--------------------------------------------------------------------------------
    Quick Start
--------------------------------------------------------------------------------

    -   Get Makery:

            $ git clone https://github.com/macro187/makery.git


    -   Declare where you put it:

            $ export MAKERY=/path/to/makery



--------------------------------------------------------------------------------
    Operating System Support
--------------------------------------------------------------------------------

    Systems with

    -   A Bash shell (or similar)

    -   Standard command-line tools

    -   A recent version of GNU Make


    Definitely

    -   Microsoft Windows 8.1 (Cygwin)

    -   Microsoft Windows 8.1 (MSYS)

    -   Gentoo Linux

    -   Mac OSX 10.5


    Probably

    -   Any other recent version of Microsoft Windows

    -   Any other recent version of Mac OSX

    -   Any Linux distribution

    -   Any BSD



--------------------------------------------------------------------------------
    .NET Support
--------------------------------------------------------------------------------

    Frameworks

    -   Microsoft .NET v1.1 through v4.6

    -   Mono v2.10 through v4.x


    Project Types

    -   Libraries

    -   Console applications

    -   ASP.NET

    -   Libraries from NuGet packages


    NuGet

    -   Download, extract, and use contents of NuGet packages


    Documentation

    -   Doxygen


    Languages

    -   C#


    Localised Embedded Resources

    -   Using Resbian tool from Halfdecent Sharp
        (http://github.com/macro187/halfdecentsharp)



--------------------------------------------------------------------------------
    Microsoft Windows
--------------------------------------------------------------------------------

    Makery has first-class support for Microsoft Windows, despite being
    implemented in Make and sh which are associated with unix-like systems.


    To run Makery on Windows, there are two options:

    -   Cygwin.  A complete unix-like environment.  Works just like any
        other unix-like operating system, so nothing special required.


    -   MSYS.  A minimal unix-like environment, and the more
        "Windows-native" option.

        An easy way to get a Makery-capable MSYS environment is to
        install Git for Windows and use its "Git Bash".

        The only additional requirement is GNU Make, which can be
        downloaded from

            https://sourceforge.net/projects/msys2/files/REPOS/MSYS2/

        Download the "make" package for your architecture and extract the
        make.exe binary into %USERPROFILE%\bin\.



--------------------------------------------------------------------------------
    Directory Structure
--------------------------------------------------------------------------------

        /my/workspace/
            solution1/
                Makefile
                project1a/
                    Makefile
                    foo.cs
                project1b/
                    Makefile
                    bar.cs
                    bat.cs
            solution2/
                Makefile
                project2a/
                    Makefile
                    baz.cs

    Figure 1. A workspace containing solution(s) containing project(s)


--------------------------------------------------------------------------------
    Projects
--------------------------------------------------------------------------------

    A project is the logical unit that Makery builds.  Projects consist of a
    directory containing a Makefile plus source materials for building one
    or more closely-related artifact(s) such as an executable, a library, or
    a website.  The Makefile declares information about the project.  The
    name of the directory serves as the project's unique name.

    Projects can depend on other projects.  Direct dependencies are declared
    by name, and Makery automatically works out transitive ones.

    Regardless of the number of projects involved in a build, Makery uses a
    single Make invocation.  It does not run Make recursively.  See
    http://miller.emu.id.au/pmiller/books/rmch/ for a discussion of this
    issue.



--------------------------------------------------------------------------------
    Solutions
--------------------------------------------------------------------------------

    A solution is a container for projects.  Solutions are directories that
    contain one or more project subdirectories, plus a Makefile that enables
    build actions across all of them.

    Solutions usually correspond to Git (or other) source code repositories.



--------------------------------------------------------------------------------
    Workspace
--------------------------------------------------------------------------------

    The workspace is the container for solutions.  It's just the parent
    directory containing all your solution subdirectories.

    Makery automatically discovers all projects in all solutions in whatever
    workspace it's being run in, so projects can depend on any other project
    as long as it's somewhere in the same workspace.



--------------------------------------------------------------------------------
    Modules
--------------------------------------------------------------------------------

    A module is a single piece of Makery build functionality.  Examples of
    the types of things modules might do:

    -   Locate source code files

    -   Create rules that perform preprocessing on source code files

    -   Locate compilers and create rules that use them to compile
        source code files

    -   Locate linkers and create rules that use them to link object
        files into programs or libraries

    -   Locate document processing programs and create rules that use
        them to generate documents from source markup

    -   Make projects executable in-place by assembling required
        artifacts from other projects

    -   Package artifacts from multiple projects into distribution
        archives

    Modules can depend on other modules.  Direct dependencies are declared
    by name, and Makery automatically works out transitive ones.

    Makery modules are named according to the pattern makery-<modulename>
    and are located by name just like any other project.  This means
    additional modules that extend the build functionality provided
    out-of-the-box by Makery can be distributed and used across solutions.



--------------------------------------------------------------------------------
    Acknowledgements
--------------------------------------------------------------------------------

    Requires GNU Make from the GNU Project
    (http://www.gnu.org/software/make/)

    Includes and uses the GNU Make Standard Library from John Graham-Cumming
    (http://gmsl.sourceforge.net/)



--------------------------------------------------------------------------------
    Licence
--------------------------------------------------------------------------------

    Copyright (c) Ron MacNeil <macro@hotmail.com>

    Permission to use, copy, modify, and distribute this software for any
    purpose with or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.

    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.