mason/README.md

# Mason #
   Mason is the build system to be used in all CyberMages projects.
Since most projects will be based on Rust it should be a straight
forward dependency link but if not then just create the front end that will
pass the required build data to the library.

## Resources ##
   The main purpose of the build system is to build resources not handled
by the projects main build tool. These resources will be located in the
projects 'resources' directory unless there is a good project specific
reason that they not be. As such the build system will look in the required
'resources' directory for the build manifest file.

## Resource Manifest Format ##
   This describes what resource files are to be built, where they are
to be placed, and what tool should be used to build them. The file should be
placed in the "resources" directory and named "resources.msnr".

   The format is a simple text file composed of sections seperated by
empty lines. Each section defines a resource to compile. The format for
each section is as follows.


name=<RESOURCE_NAME>
type=<RESOURCE_TYPE>
src=<RELATIVE_PATH_TO_RESOURCE>
dst=<RELATIVE_PATH_FOR_COMPILED_DATA>
compiler=<COMPILER_TOOL>
args=<ARGUMENTS_TO_PASS>


The name of the resource should be unique and will be used as a reference in
the loader manifest file.

The type of the resource is a string passed to the loader manifest to denote
the type of resource that this is. This is ment to act as a hint for the
correct loader to use. Examples would be: model, image, etc.

src is the path, relative to the resource directory, for the file
that needs to be compiled.

dst is the path, relative to the project output directory, for the file's
compiled output to be placed. Directories will be created as needed.

compiler is the compilation tool, the executable to call, to use
for compiling the resource. If the tool has an extension then make sure to
specify it. For example: "builder.exe". "copy" can be used as a compiler
as well. The copy tool will just copy the resource to the destination. If
no compiler is defined then mason will check its configuration files for
a compiler associated with the given file type. If no compiler is found then
mason will default to using the copy compiler.

args are the arguments to pass to the compiler.

## Loader Manifest Format ##
   Mason will create a loader manifest to aid in the loading of project
resources. This manifest file will be located at the root of the
output directory. It will be named "resources.msnl".

   The loader manifest file i a binary format using little endian byte order.

The file starts with a simple header that contains a magic number which
reads 'MSNL' in ascii and some version information.

    bytes |  Type  | meaning
   -------|--------|--------
      0   | uint8  | magic number (M)
      1   | uint8  | magic number (S)
      2   | uint8  | magic number (N)
      3   | uint8  | magic number (L)
      4   | uint8  | major version
      5   | uint8  | minor version

Following the header is a section dealing with the resources
that were compiled. It has the amount of resource entries in the section
followed by each resource entry.

    bytes |  Type  | meaning
   -------|--------|---------
    0->7  | uint64 | Amount of resource entries.i
    8->a  | Entry  | A resource entry.
    a->b  | Entry  | A resource entry.
    b->c  | Entry  | A resource entry.
    c->d  | Entry  | A resource entry.
    ....  |  ....  |         ....

Each resource entry will have a unique name to use for referencing it
followed by the type string of the resource and the path to where
the resource file should be found. These three strings are all utf-8 formated.
Each string is preceded by the length of bytes to read for that string. This
is needed because null bytes are allowed to be within the string. The Path
to the resource is relative to the output directory's root.

    bytes |  Type  | meaning
   -------|--------|--------------
    0->7  | uint64 | Resource name length.
    8->n  | utf-8  | Resource name.
 n+1->n+8 | uint64 | Type length.
   n+9->m | utf-8  | Type.
 m+1->m+8 | uint64 | Path length.
   m+9->p | utf-8  | Path to the resource.