.TH mrc 1 "2020-09-11" "version 1.2.2" "User Commands"
.if n .ad l
.nh
.SH NAME
mrc \- A resource compiler
.SH SYNOPSIS
mrc [\fB-o\fR|\fB--output\fR outputfile]
    [\fB--root\fR arg]
    [\fB--resource-prefix\fR arg]
    [\fB--elf-machine\fR arg]
    [\fB--elf-class\fR arg]
    [\fB--elf-data\fR arg]
    [\fB--elf-flags\fR arg]
    file1 [file2...]
.sp
mrc [\fB-h\fR|\fB--help\fR]
.sp
mrc [\fB-v\fR|\fB--version\fR]
.sp
mrc [\fB--header\fR] > mrsrc.h
.sp
 #include "mrsrc.h"
 void foo()
 {
   mrsrc::rsrc data("/alerts/text.txt");
   if (data) {
     mrsrc::istream is(data);
     ...
   }
 }
.SH DESCRIPTION
Many applications come with supplementary data. This data is
usually stored on disk as regular files. The disadvantage of
this procedure is that an application cannot simply be copied
to another location or computer and expected to function properly.
.sp
Resources are a way to overcome this problem by including all
data inside the executable file. The mrc resource compiler can
create object files containing both the data and an index. This
data can then be accessed from within an application using
.BR C++
classes.
.SH OPTIONS
.TP
[\fB-o\fR|\fB--output\fR] file
Specify the output file, the resulting file will be an object file
you can link together with the rest of your object files into an
executable file.
.TP
\fB--root\fR
The resources are accessed using a path. You can specify the root part
of the path using this parameter.
.TP
\fB--resource-prefix\fR name
Use this option to specify another name for the global variables
in the data section.
.TP
\fB--elf-machine\fR arg
By default mrc assumes you want to create a resource file for the
machine it runs on. But using this option you can create files for
other architectures, useful when cross compiling.
.sp
The machine flag is used to specify the value of the \fIe_machine\fR
field in the ELF header.
.TP
\fB--elf-class\fR number
The ELF class to use, should be either \fI1\fR for 32-bit objects or
\fI2\fR for 64-bit objects.
.TP
\fB--elf-data\fR number
The ELF data endianness to use, should be either \fI1\fR for little-endian
(=LSB) objects or \fI2\fR for big-endian (=MSB) objects.
.TP
\fB--elf-flags\fR number
A value to store in the \fIe_flags\fR field of the ELF header. This can
contain the EABI version for ARM e.g.
.TP
\fB--header\fR
This option will print a \fBmrsrc.h\fR file to \fBstdout\fR which
you can write to disk and use to access resources.
.TP
[\fB-v\fR|\fB--verbose\fR]
Print debug output, useful to track where all data ends up in the
resource.
.TP
\fB--version\fR
Print version number and exit.
.TP
[\fB-h\fR|\fB--help\fR]
Print simple help summary and exit.
.TP
file [file...]
One or more files to include in the resource file. Directory names
can be used as well. All regular files end up in the root of the
resource tree, files found in directories end up in directies in
the resource tree. The following rules apply:
.sp
Regular files are added in the root of the resource tree using
their proper file name.
.sp
If the file name refers to a directory, the directory is traversed
recursively and all files are added. If the file name ends with a
forward slash (/) files are added to the root. If the file does
not end with a slash, the name of the directory will be placed
in the root and all contained files will be placed beneath this.
.sp
.SH EXAMPLES
.PP
Here's a list of usage cases.
.TP
mrc -o x.o my-resource.txt my-image.png
Will create a resource file containing two resources accessible
using the path "/my-resource.txt" and "/my-image.png" respectively.
.TP
mrc -o x.o img/my-image.png
Will create a resource file containing a single resource accessible
using the path "/my-image.png".
.TP
mrc -o x.o img/
Assuming there are two images in the directory img called
my-image-1.png and my-image-2.png, the resource file will contain
them both accessible under the name "/my-image-1.png" and
"/my-image-1.png".
.sp
mrc -o x.o img
Same as the previous, but note there's no trailing slash,
the resource file will contain both images but they are now
accessible under the name "/img/my-image-1.png" and
"/img/my-image-1.png".
.PP
Use the verbose flag (\fB--verbose\fR) to track what ends up where.
.SH DETAILS
.sp
The way this works is that mrc first collects all data from the
files specified, including the files found in specified directories.
An simple index is created to allow hierarchical access to the data.
The data is then flattened into three data structures and these
are written to the \fB.data\fR section of the object file. The
three data blobs are then made available as globals in your
application with the names \fBgResourceIndex\fR,
\fBgResourceName\fR and \fBgResourceData\fR. You can specify the
prefix part of this variable with the -fB--resource-prefix\fR option.
.sp
The index entries have the following format:
    struct rsrc_imp
    {
        unsigned int m_next;   // index of the next sibling entry
        unsigned int m_child;  // index of the first child entry
        unsigned int m_name;   // offset of the name for this entry
        unsigned int m_size;   // data size for this entry
        unsigned int m_data;   // offset of the data for this entry
    };
.sp
The classes in the \fBmrsrc.h\fR file are contained in the
namespace \fBmrsrc\fR. The available classes are
.TP
\fBmrsrc::rsrc\fR
This is the basic class to access data. It has a constructor that
takes a path to a resource. Data can be accessed using the \fBdata\fR
method and the size of the data is available via the \fBsize\fR method.
If the resource was not found, \fBdata\fR will return \fBnullptr\fR and
\fBsize\fR will return zero. You can also use \fBoperator bool\fR to
check for valid data.
.TP
\fBmrsrc::streambuf\fR
This class is derived from \fBstd::streambuf\fR. It can take both a
\fBmrsrc::rsrc\fR or a path as constructor parameter.
.sp
.TP
\fBmrsrc::istream\fR
This class is derived from \fBstd::istream\fR. It can take both a
\fBmrsrc::rsrc\fR or a path as constructor parameter.
.SH BUGS
This application can only generate ELF formatted object files.
.sp
Only a single resource entry can be generated and there's no
way to merge or manipulate resource files yet.