Describe the resources directory in a README document

1 files changed, 61 insertions, 0 deletions

diff --git a/docs/README.resources b/docs/README.resources
new file mode 100644
index 000000000..7ed67b23a
--- /dev/null
+++ b/docs/README.resources
@@ -0,0 +1,61 @@
+Starting with version 0.79, DOSBox Staging needs access to 
+bundled resource files.
+
+Meson will construct the deliverable "resources/" directory 
+along-side the compiled executable. This layout can be shipped 
+as-is. The executable will check the following paths for the 
+resources, in the following priority order:
+
+1. Beside the executable:
+    ./dosbox (executable)
+    ./resources/subdirs/...
+    (on macOS: ../Resources/subdirs/...)
+
+   This first instance should also be the prefered packaging
+   layout for wrapped formats like FlatPak, Snap, etc.
+
+2. Up one directory from the executable (which allows unit tests 
+   to access resources):
+    ./dosbox
+    ./../resources/subdirs/...
+    (on macOS: ../../Resources/subdirs/...)
+
+3. In the absolute path:
+    '/usr/local/share/dosbox-staging/subdirs/...'
+
+4. In the absolute path:
+   '/usr/share/dosbox-staging/subdirs/...'
+
+5. If your OS has a different prefered "application content" 
+   holding area, please open a ticket.
+
+6. In the user's configuration path:
+   'home/<user>/.config/dosbox/subdirs/...'
+   (or the Windows configuration path)
+
+FAQ:
+Q: Why can't these be embedded inside the executable?
+
+A1: Source files aren't filesystems, as such storing binaries as 
+    massive hex strings is a form of obfuscation that makes it 
+    harder to understand what they contain. With files, anyone 
+    can diff or create an md5 checksum. With files, anyone can 
+    notify the project when a file has become outdated.
+
+A2: Turning binary files into source involves placing tens of 
+    thousands of lines of hex address strings into your code 
+    base.
+
+    These get parsed and become a persistent carrying "load" for 
+    editors and development IDEs.  They also become a source of
+    false-positive hits when grepping text files.
+
+Q: How are the resources/ deployed into the build area by Meson?
+A: Read ./contrib/resources/meson.build This meson file copies
+   the deployable resource files into the build area.
+
+Q: How are the resources/ deployed into the build area by Visual
+   Studio?
+A: Search the vcxproj files for "contrib\resources". These
+   snippets perform the copying.
+