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 - `rsync` (version 3.0 or later)
  95 - `sed`
  96 - `test`
  97
  98 The following varibales provide general configuration :⁠—
  99
 100 - **`BUILDTARGET`:**
 101   A file whose timestamp is guaranteed to be updated on every build
 102     (default: `.grass`).
 103   👥📤 Yseme will compare the modified time of this file to the commit
 104     time of the latest commit to determine if the build is out·of·date.
 105
 106 - **`DESTDIR`:**
 107   The directory which contains the result of the build.
 108   `rsync` will be called from this directory.
 109
 110 The following variables configure Git :⁠—
 111
 112 - **`GITFORCE`:**
 113   If this variable has a value, the current branch does not need to be
 114     up·to·date with its remote counterpart and a force‐push will be
 115     used (default: empty).
 116
 117 - **`GITOPTS`:**
 118   Options to pass to Git (default: empty).
 119
 120 The following variables configuer R·Sync :⁠—
 121
 122 - **`CLIENTCHARSET`:**
 123   The character set of the local machine (default: `utf-8-mac`).
 124   If both this and `SERVERCHARSET` are set and not equal, an appropriate
 125     `--iconv` option will be added to the R·Sync call.
 126
 127 - **`RSYNCFILTER`:**
 128   The location (relative to the working directory) of an R·Sync filter
 129     file (default: `.rsync-filter` if such a file exists; otherwise,
 130     empty).
 131
 132 - **`RSYNCOPTS`:**
 133   Option to use when calling R·Sync.
 134   The following flags are set by default :⁠—
 135     `--checksum`, `--compress`, `--del`, `--links`, `--omit-dir-times`,
 136     `--prune-empty-dirs`, `--recursive`, `--times`, `--verbose`.
 137   Additional flags may be set depending on the values of variables and
 138     which target is being built (e·g `dry-sync` 🆚 `sync`).
 139
 140 - **`SERVER`:**
 141   The remote machine to sync to (default: `computer`).
 142
 143 - **`SERVERCHARSET`:**
 144   The character set of the remote machine (default: `utf-8`).
 145   If both this and `CLIENTCHARSET` are set and not equal, an appropriate
 146     `--iconv` option will be added to the R·Sync call.
 147
 148 - **`SERVERPATH`:**
 149   The path on the remote machine to sync to (default: the name of the
 150     current directory).
 151
 152 If you use a method of syncing your website other than `rsync`, you can
 153   still use 👥📤 Yseme:
 154 Just define your own `sync` and `dry-sync` targets which depend on
 155  👥📤 Yseme’s `ensure-clean`, `ensure-branch-up-to-date`, and
 156  `ensure-build`.
 157
 158 [touch_grass]: <https://blog.ladys.computer/2023-05-06/touch_grass/> "C·I pipelines have you down? Why not ‹ touch .grass ›?!"