mrc(1)

💖 mrc — a resource compiler 💖

okay bestie, welcome to mrc(1), the User Commands girlie of the manual pages. she's a resource compiler and she's literally carrying your app's whole vibe. let's get into it 🫶

---

✨ SYNOPSIS ✨

like, the shape of it:

mrc [-o|--output outputfile]
    [--root arg]
    [--resource-prefix arg]
    [--elf-machine arg]
    [--elf-class arg]
    [--elf-data arg]
    [--elf-abi arg]
    [--elf-flags arg]
    file1 [file2...]

mrc [-h|--help]

mrc [-v|--version]

mrc [--header] > mrsrc.h

 #include "mrsrc.h"
 void foo()
 {
   mrsrc::rsrc data("/alerts/text.txt");
   if (data) {
     mrsrc::istream is(data);
     ...
   }
 }

---

🌸 DESCRIPTION 🌸

so most apps come with supplementary data, right? and normally that data just sits on disk as regular files. the disadvantage is kinda obvious: you can't just copy an application to another location or another computer and expect it to, like, function properly. it breaks. embarrassing for everyone. 💀

resources are how we fix that — by including all the data inside the executable file. the mrc resource compiler can create object files that contain both the data and an index. then your application can access that data from within itself using C++ classes. main character energy honestly. 👑

---

🎀 OPTIONS 🎀

• [-o|--output] file — specify the output file. the resulting file is an object file you can link together with the rest of your object files into an executable file. iconic.
• --root — resources are accessed using a path, and this parameter lets you specify the root part of that path. 💅
• --resource-prefix name — use this to specify another name for the global variables in the data section. rename your babies, slay.
• --elf-machine arg — by default mrc assumes you want to create a resource file for the machine it runs on. but with this option you can create files for other architectures — super useful when cross compiling. the machine flag is used to specify the value of the e_machine field in the ELF header.
• --elf-class number — the ELF class to use. should be either 1 for 32-bit objects or 2 for 64-bit objects.
• --elf-data number — the ELF data endianness to use. should be either 1 for little-endian (=LSB) objects or 2 for big-endian (=MSB) objects.
• --elf-abi number — the ELF OS ABI flag to use. the exact value for this flag should be looked up in elf.h. default is to use the value for the current architecture. (value of 3 is for Linux, 9 is for FreeBSD. iykyk 🧚)
• --elf-flags number — a value to store in the e_flags field of the ELF header. this can contain the EABI version for ARM e.g.
• --coff type — when this option is specified, a COFF file is created for use on Windows. the argument type should be one of x64, x86 or arm64.
• --header — this option will print a mrsrc.h file to stdout which you can write to disk and use to access resources. use with the --output option to write to a file instead.
• [-v|--verbose] — print debug output. useful to track where all data ends up in the resource. lowkey essential ngl.
• --version — print version number and exit.
• [-h|--help] — print simple help summary and exit.
• 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, and files found in directories end up in directories in the resource tree. the following rules apply:
  • regular files are added in the root of the resource tree using their proper file name.
  • 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.

---

🌈 EXAMPLES 🌈

here's a list of usage cases, bestie. study them, they ate. 🔥

• 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.
• mrc -o x.o img/my-image.png — will create a resource file containing a single resource accessible using the path "/my-image.png".
• 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".

mrc -o x.o img — same as the previous, but note there's no trailing slash, so 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".

• use the verbose flag (--verbose) to track what ends up where. 🦋

---

💜 DETAILS 💜

the way this works is that mrc first collects all data from the files specified, including the files found in specified directories. a 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 .data section of the object file. the three data blobs are then made available as globals in your application with the names gResourceIndex, gResourceName and gResourceData. you can specify the prefix part of this variable with the -fB--resource-prefix option.

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
};

🌟 the classes in mrsrc.h

they're contained in the namespace mrsrc. the available classes are:

• mrsrc::rsrc — 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 data method and the size of the data is available via the size method. if the resource was not found, data will return nullptr and size will return zero. you can also use operator bool to check for valid data.
• mrsrc::streambuf — this class is derived from std::streambuf. it can take both a mrsrc::rsrc or a path as constructor parameter.
• mrsrc::istream — this class is derived from std::istream. it can take both a mrsrc::rsrc or a path as constructor parameter.

---

😭 BUGS 😭

this application can only generate ELF formatted object files on machines that have an <elf.h> header file installed. no header, no vibes. sorry bestie.

only a single resource entry can be generated and there's no way to merge or manipulate resource files yet. it's giving "we're working on it" 💀

---

and that's the whole page, periodt. 💅 this was mrc, version 1.3.6, dated 2022-12-03 — the mrc(1) manual page, lovingly delivered to you from the User Commands section. go forth and embed your data, queen 👑💖