Merge branch 'fix-203' into 'main'

build.rs: Add some documentation to reduce confusion in newcomers

Closes #203

See merge request subplot/subplot!183

1 files changed, 39 insertions, 2 deletions

diff --git a/build.rs b/build.rs
index 7228ce0..1852601 100644
--- a/build.rs
+++ b/build.rs
@@ -1,11 +1,39 @@
-// Build script for Subplot, locates and builds the embedded resource set from
-// the share directory
+//! Subplot build script.
+//!
+//! This code is run as part of `cargo build` and is used to walk the `share/`
+//! directory and include the contents therein as embedded resources in the
+//! subplot binary as well as a few other things.
+//!
+//! https://doc.rust-lang.org/cargo/reference/build-scripts.html
+//!
+
+//! The output of this script is some directives to Cargo as to when to rerun
+//! the build script for subplot (by watching the share/ tree) and also a file
+//! which is included directly as the `EMBEDDED_FILES` constant in the
+//! `src/resources.rs` file.
+//!
+//! Finally the script checks for the `DEB_BUILD_OPTS` environment variable and
+//! if set, it causes a resource fallback path of `/usr/share/subplot` to be
+//! added to the resources search path automatically.
 
 use anyhow::Result;
 use std::io::Write;
 use std::path::{Component, Path, PathBuf};
 use walkdir::WalkDir;
 
+/// Decide if a path in `share/` should be ignored.
+///
+/// We ignore paths which contain any component which meets any
+/// of the following criteria:
+///
+/// 1. Starting with a `.`
+/// 2. Ending with `~` or `.bak`
+/// 3. being called `__pycache__`
+/// 4. Not being valid unicode
+///
+/// The last item is important because the inputs to subplot are all
+/// utf-8 encoded files, so we want to be sure any resources can be referred
+/// to, which means they must be unicode compliant too.
 fn path_ignore(path: &Path) -> bool {
     // We have a number of rules for ignoring any given path.
     path.components().any(|component| {
@@ -33,6 +61,10 @@ fn path_ignore(path: &Path) -> bool {
     })
 }
 
+/// Gather the `share/` files for inclusion in the binary.
+///
+/// This walks the `share/` tree in the source code and for any files therein,
+/// which are not ignored by [`path_ignore()`] we add them to the return list.
 fn gather_share_files() -> Result<Vec<PathBuf>> {
     let base_path = Path::new(env!("CARGO_MANIFEST_DIR")).join("share");
     println!("cargo:rerun-if-changed={}", base_path.display());
@@ -62,6 +94,11 @@ fn gather_share_files() -> Result<Vec<PathBuf>> {
     Ok(ret)
 }
 
+/// Write out the resource file for inclusion into subplot.
+///
+/// This takes the list of files generated by [`gather_share_files()`] and
+/// creates a source file which can be included into subplot which causes all
+/// those files and their contents to be embedded into the subplot binary.
 fn write_out_resource_file<'a>(paths: impl Iterator<Item = &'a Path>) -> Result<()> {
     let mut out_path: PathBuf = std::env::var("OUT_DIR")?.into();
     out_path.push("embedded_files.inc");