+# 👥📤 Yseme
+
+**A make·file for syncing.**
+
+👥📤 Yseme is an implementation of the sync process described in my
+ blogpost [<cite>C·I pipelines have you down? Why not ‹ touch
+ .grass ›?!</cite>][touch_grass].
+It is intended to be included in projects as a Git submodule, and
+ recursively called from within another make·file.
+
+**Note:**
+👥📤 Yseme requires functionality present in G·N·U Make 3.81 (or
+ later) and will not work in previous versions, or other
+ implementations of Make.
+Compatibility with later versions of G·N·U Make is assumed, but not
+ tested.
+
+## Nomenclature
+
+<i>Yseme</i> combines two archaic English terms: <i>y‐</i> (indicating
+ togetherness or wholeness) and <i>seme</i> (< Old Norse <i>sǿmr</i>,
+ meaning “seemly”, “appropriate”, or “beautiful”).
+
+## Basic Usage
+
+`make dry-sync` will ensure that the current repository is clean,
+ built, and up‐to‐date, and then perform a dry run (`--dry-run`) of
+ R·Sync.
+`make sync` will perform the same checks, then push any new commits and
+ perform an actual run of R·Sync.
+
+👥📤 Yseme is intended to be called recursively from with·in another
+ make·file.
+The following is a sample make·file which makes use of 👥📤 Yseme :—
+
+```make
+SHELL = /bin/sh
+
+# © 2024 Lady [@ Lady’s Computer].
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
+
+# Assume 👥📤 Yseme is a git submodule located at <.yseme> in the
+# current directory.
+YSEME := .yseme
+YSEMEVARS := DESTDIR='public'
+
+# Build script (substitute with your own).
+build:
+ if [ ! -d public ]; then mkdir public; fi
+ echo 'Hello, world!' > public/index
+ touch .grass
+
+# Set up the 👥📤 Yseme submodule.
+$(YSEME)/GNUmakefile:
+ git submodule update --init $(YSEME)
+
+# Reload this make·file if the 👥📤 Yseme make·file has changed.
+# (Replace `GNUmakefile´ with whatever your make·file is called.)
+#
+# This is required to ensure the correct value of the `YSEME_TARGETS´ variable.
+#
+# See <https://www.gnu.org/software/make/manual/html_node/Remaking-Makefiles.html>.
+GNUmakefile: $(YSEME)/GNUmakefile
+ touch GNUmakefile
+
+# Ensure the 👥📤 Yseme make·file exists before running the following commands.
+ifneq ($(wildcard $(YSEME)/GNUmakefile),)
+# Programmatically get the list of phony targets defined by 👥📤 Yseme.
+# You can also list these manually (e·g `sync´, `dry-sync´).
+YSEME_TARGETS := $(shell sed '/^\.PHONY[ :]/!d;/^\.PHONY[ :]/s/ *;.*//;/^\.PHONY[ :]/s/\.PHONY.*: *//' < $(YSEME)/GNUmakefile)
+
+# For each target defined by 👥📤 Yseme, forward it appropriately.
+$(YSEME_TARGETS):
+ $(MAKE) -f $(YSEME)/GNUmakefile $@ $(YSEMEVARS)
+endif
+```
+
+👥📤 Yseme was designed and tested with G·N·U Make 3.81.
+It likely works with newer versions of Make, but may break in older
+ versions.
+
+## Setup and Configuration
+
+👥📤 Yseme depends on the following programs to run.
+In every case, you may supply your own implementation by overriding the
+ corresponding (allcaps) variable (e·g, set `RSYNC` to supply your own
+ `rsync` implementation).
+
+- `awk`
+- `echo`
+- `git`
+- `rsync` (version 3.0 or later)
+- `sed`
+- `test`
+
+The following varibales provide general configuration :—
+
+- **`BUILDTARGET`:**
+ A file whose timestamp is guaranteed to be updated on every build
+ (default: `.grass`).
+ 👥📤 Yseme will compare the modified time of this file to the commit
+ time of the latest commit to determine if the build is out·of·date.
+
+- **`DESTDIR`:**
+ The directory which contains the result of the build.
+ `rsync` will be called from this directory.
+
+The following variables configure Git :—
+
+- **`GITFORCE`:**
+ If this variable has a value, the current branch does not need to be
+ up·to·date with its remote counterpart and a force‐push will be
+ used (default: empty).
+
+- **`GITOPTS`:**
+ Options to pass to Git (default: empty).
+
+The following variables configuer R·Sync :—
+
+- **`CLIENTCHARSET`:**
+ The character set of the local machine (default: `utf-8-mac`).
+ If both this and `SERVERCHARSET` are set and not equal, an appropriate
+ `--iconv` option will be added to the R·Sync call.
+
+- **`RSYNCFILTER`:**
+ The location (relative to the working directory) of an R·Sync filter
+ file (default: `.rsync-filter` if such a file exists; otherwise,
+ empty).
+
+- **`RSYNCOPTS`:**
+ Option to use when calling R·Sync.
+ The following flags are set by default :—
+ `--checksum`, `--compress`, `--del`, `--links`, `--omit-dir-times`,
+ `--prune-empty-dirs`, `--recursive`, `--times`, `--verbose`.
+ Additional flags may be set depending on the values of variables and
+ which target is being built (e·g `dry-sync` 🆚 `sync`).
+
+- **`SERVER`:**
+ The remote machine to sync to (default: `computer`).
+
+- **`SERVERCHARSET`:**
+ The character set of the remote machine (default: `utf-8`).
+ If both this and `CLIENTCHARSET` are set and not equal, an appropriate
+ `--iconv` option will be added to the R·Sync call.
+
+- **`SERVERPATH`:**
+ The path on the remote machine to sync to (default: the name of the
+ current directory).
+
+If you use a method of syncing your website other than `rsync`, you can
+ still use 👥📤 Yseme:
+Just define your own `sync` and `dry-sync` targets which depend on
+ 👥📤 Yseme’s `ensure-clean`, `ensure-branch-up-to-date`, and
+ `ensure-build`.
+
+[touch_grass]: <https://blog.ladys.computer/2023-05-06/touch_grass/> "C·I pipelines have you down? Why not ‹ touch .grass ›?!"
Lady’s Gitweb / Yseme / commitdiff