Lady’s Gitweb - Yseme/blob - README.markdown

   1 # 👥📤 Yseme
   2
   3 **A make·file for syncing.**
   4
   5 👥📤 Yseme is an implementation of the sync process described in my
   6   blogpost [<cite>C·I pipelines have you down? Why not ‹ touch
   7   .grass ›?!</cite>][touch_grass].
   8 It is intended to be included in projects as a Git submodule, and
   9   recursively called from within another make·file.
  10
  11 **Note:**
  12 👥📤 Yseme requires functionality present in G·N·U Make 3.81 (or
  13   later) and will not work in previous versions, or other
  14   implementations of Make.
  15 Compatibility with later versions of G·N·U Make is assumed, but not
  16   tested.
  17
  18 ## Nomenclature
  19
  20 <i>Yseme</i> combines two archaic English terms: <i>y‐</i> (indicating
  21   togetherness or wholeness) and <i>seme</i> (< Old Norse <i>sǿmr</i>,
  22   meaning “seemly”, “appropriate”, or “beautiful”).
  23
  24 ## Basic Usage
  25
  26 `make dry-sync` will ensure that the current repository is clean,
  27   built, and up‐to‐date, and then perform a dry run (`--dry-run`) of
  28   R·Sync.
  29 `make sync` will perform the same checks, then push any new commits and
  30   perform an actual run of R·Sync.
  31
  32 👥📤 Yseme is intended to be called recursively from with·in another
  33   make·file.
  34 The following is a sample make·file which makes use of 👥📤 Yseme :⁠—
  35
  36 ```make
  37 SHELL = /bin/sh
  38
  39 # © 2024 Lady [@ Lady’s Computer].
  40 #
  41 # This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
  42 # If a copy of the M·P·L was not distributed with this file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
  43
  44 # Assume 👥📤 Yseme is a git submodule located at <.yseme> in the
  45 # current directory.
  46 YSEME := .yseme
  47 YSEMEVARS := DESTDIR='public'
  48
  49 # Build script (substitute with your own).
  50 build:
  51         if [ ! -d public ]; then mkdir public; fi
  52         echo 'Hello, world!' > public/index
  53         touch .grass
  54
  55 # Set up the 👥📤 Yseme submodule.
  56 $(YSEME)/GNUmakefile:
  57         git submodule update --init $(YSEME)
  58
  59 # Reload this make·file if the 👥📤 Yseme make·file has changed.
  60 # (Replace `GNUmakefile´ with whatever your make·file is called.)
  61 #
  62 # This is required to ensure the correct value of the `YSEME_TARGETS´ variable.
  63 #
  64 # See <https://www.gnu.org/software/make/manual/html_node/Remaking-Makefiles.html>.
  65 GNUmakefile: $(YSEME)/GNUmakefile
  66         touch GNUmakefile
  67
  68 # Ensure the 👥📤 Yseme make·file exists before running the following commands.
  69 ifneq ($(wildcard $(YSEME)/GNUmakefile),)
  70 # Programmatically get the list of phony targets defined by 👥📤 Yseme.
  71 # You can also list these manually (e·g `sync´, `dry-sync´).
  72 YSEME_TARGETS := $(shell sed '/^\.PHONY[ :]/!d;/^\.PHONY[ :]/s/ *;.*//;/^\.PHONY[ :]/s/\.PHONY.*: *//' < $(YSEME)/GNUmakefile)
  73
  74 # For each target defined by 👥📤 Yseme, forward it appropriately.
  75 $(YSEME_TARGETS):
  76         $(MAKE) -f $(YSEME)/GNUmakefile $@ $(YSEMEVARS)
  77 endif
  78 ```
  79
  80 👥📤 Yseme was designed and tested with G·N·U Make 3.81.
  81 It likely works with newer versions of Make, but may break in older
  82   versions.
  83
  84 ## Setup and Configuration
  85
  86 👥📤 Yseme depends on the following programs to run.
  87 In every case, you may supply your own implementation by overriding the
  88   corresponding (allcaps) variable (e·g, set `RSYNC` to supply your own
  89   `rsync` implementation).
  90
  91 - `awk`
  92 - `echo`
  93 - `git`
  94 - `grep`
  95 - `iconv`
  96 - `rsync` (version 3.0 or later)
  97 - `sed`
  98 - `test`
  99
 100 The following varibales provide general configuration :⁠—
 101
 102 - **`BUILDTARGET`:**
 103   A file whose timestamp is guaranteed to be updated on every build
 104     (default: `.grass`).
 105   👥📤 Yseme will compare the modified time of this file to the commit
 106     time of the latest commit to determine if the build is out·of·date.
 107
 108 - **`DESTDIR`:**
 109   The directory which contains the result of the build.
 110   `rsync` will be called from this directory.
 111
 112 The following variables configure Git :⁠—
 113
 114 - **`GITFORCE`:**
 115   If this variable has a value, the current branch does not need to be
 116     up·to·date with its remote counterpart and a force‐push will be
 117     used (default: empty).
 118
 119 - **`GITOPTS`:**
 120   Options to pass to Git (default: empty).
 121
 122 The following variables configuer R·Sync :⁠—
 123
 124 - **`CLIENTCHARSET`:**
 125   The character set of the local machine (default: `utf-8-mac` if
 126     supported by `iconv`; `utf-8` otherwise).
 127   If both this and `SERVERCHARSET` are set and not equal, an appropriate
 128     `--iconv` option will be added to the R·Sync call.
 129
 130 - **`RSYNCFILTER`:**
 131   The location (relative to the working directory) of an R·Sync filter
 132     file (default: `.rsync-filter` if such a file exists; otherwise,
 133     empty).
 134
 135 - **`RSYNCOPTS`:**
 136   Option to use when calling R·Sync.
 137   The following flags are set by default :⁠—
 138     `--checksum`, `--compress`, `--del`, `--links`, `--omit-dir-times`,
 139     `--prune-empty-dirs`, `--recursive`, `--times`, `--verbose`.
 140   Additional flags may be set depending on the values of variables and
 141     which target is being built (e·g `dry-sync` 🆚 `sync`).
 142
 143 - **`SERVER`:**
 144   The remote machine to sync to (default: `computer`).
 145
 146 - **`SERVERCHARSET`:**
 147   The character set of the remote machine (default: `utf-8`).
 148   If both this and `CLIENTCHARSET` are set and not equal, an appropriate
 149     `--iconv` option will be added to the R·Sync call.
 150
 151 - **`SERVERPATH`:**
 152   The path on the remote machine to sync to (default: the name of the
 153     current directory).
 154
 155 If you use a method of syncing your website other than `rsync`, you can
 156   still use 👥📤 Yseme:
 157 Just define your own `sync` and `dry-sync` targets which depend on
 158  👥📤 Yseme’s `ensure-clean`, `ensure-branch-up-to-date`, and
 159  `ensure-build`.
 160
 161 [touch_grass]: <https://blog.ladys.computer/2023-05-06/touch_grass/> "C·I pipelines have you down? Why not ‹ touch .grass ›?!"