The upcoming mulle-objc 0.22.1 release (III): README.md CMS

A README.md CMS

As talked about often on these pages, the number of github projects that are affected with each release is huge. For this release it’s close to a hundred projects, each with its own versioning and README.md. Certain other projects, like MulleUI, aren’t yet in a releaseable state, but they will appear eventually. These “below the surface” projects add up to maybe another hundred projects.

Maintaining all these README.mds by hand takes a lot of time during a release. But these README.mds have a lot in common and some of the information can be generated from the project information by scripts.

That’s all perfect for templating. As the project already has a sophisticated template generator mulle-scion, it was fairly easy to create the mulle-readme-cms project.

mulle-readme-cms

Drawing from biology terminology, each README.md is created with a README.md.scion template, that pulls buds and plist files (JSON or XML would be OK too) from a cola directory, and combines them to form the README.md content.

As an example here is a snippet off README.md.scion as used by mulle-c:

{% if not config.skipDescription %}
{%  includes optionally "description.md.bud" %}
{% endif %}

{% if not config.skipAuthor %}
{%  includes optionally "author.md.bud" %}
{% endif %}

The description is germane to each individual prioject, but the author information is the same most of the time.

So in a central cola shared by all mulle-c projects there is

cola
├── author.md.bud
├── author.plist
└── README.md.scion

author.md.bud:

## Author

{% for author in authors %}
[{{ author.name }}]({{ author.url }}){{ author.organization ? [@" for " stringByAppendingString:author.organization] : "" }}
{% endfor %}

and authors.plist:

{
   authors =
   (
      {
         name="Nat!";
         url="https://mulle-kybernetik.com/weblog";
         organization="Mulle kybernetiK"
      }
   )
}

These values can then be overridden by plist files and bud files in the cola folder of the project.

Long term pitfalls

The information for an individual project is gathered with mulle-project-properties-plist to create a file like this:

{
   project =
   {
      description="#️⃣ A collection of hash functions";
      domain="github";
      name="mulle-data";
      user="mulle-c";
      repo="mulle-data";
      homepage="https://github.com/mulle-c/mulle-data";
      license="BSD-3-Clause"
   };
   dependencies =
   (
      {
         description="🔀 Cross-platform C compiler glue (and some cpp conveniences)";
         domain="github";
         name="mulle-c11";
         repo="mulle-c11";
         url="https://github.com/mulle-c/mulle-c11";
         user="mulle-c";
      }
   )
}

This information is then transformed into markdown with a scion template and mulle-scion. A problem though appears now, that this properties.plist file is now a duplicate of settings contained in the mulle-sde environment and the sourcetree .mulle/etc/sourcetree/config as well as some other files like .mulle/etc/project/version.sh.

This is unfortunate as there is a tendendency I have noted in myself, to edit properties.plist itself, though I shouldn’t. The lack of a clearly defined central place for this information (most likely the best place is the “project” environment) is a blemish I should correct in the next version.

Project related tools

The mulle-project-pacman-pkg script, can produce arch PKGBUILD files:

pkgname=mulle-buffer
pkgver=3.3.0
pkgrel=1
pkgdesc="↗️ A growable C char array and also a stream"
url="https://github.com/mulle-c/mulle-buffer.git"
license=('BSD-3-Clause')
source=("https://github.com/mulle-c/mulle-buffer/archive/3.3.0.tar.gz")
sha256sums=('6e43ecf2f1ae96e604ae53c370cb0e45fd4ec2340974693923af55acca7c39ed')
arch=('i686' 'x86_64' 'ppc' 'aarm')
options=('staticlibs')
depends=('mulle-allocator'
         'mulle-data')

build()
{
   cmake -B build \
         -S "${srcdir}/${pkgname}-${pkgver}" \
         -DCMAKE_INSTALL_PREFIX=/usr \
         -DCMAKE_PREFIX_PATH=/usr \
         -DCMAKE_BUILD_TYPE=Release &&
   cmake --build build --config Release
}

package()
{
   DESTDIR="${pkgdir}" \
      cmake --install build --config Release
}

The mulle-project-git-submodule script produces shell commands to import dependencies as git submodules if you so desire:

git submodule add https://github.com/mulle-c/mulle-allocator submodule/mulle-allocator
git submodule add https://github.com/mulle-c/mulle-c11 submodule/mulle-c11
git submodule add https://github.com/mulle-c/mulle-data submodule/mulle-data
mulle-sde environment --global set MULLE_FETCH_SEARCH_PATH '${PWD}/submodule:${MULLE_FETCH_SEARCH_PATH}'

mulle-project-package-json produces NPM compatible package.json output:

{
   "name" : "mulle-buffer",
   "version" : "3.3.0",
   "description" : "↗️ A growable C char array and also a stream",
   "homepage" : "https://github.com/mulle-c/mulle-buffer",
   "bugs" : "https://github.com/mulle-c/mulle-buffer/issues",
   "keywords" : [],
   "license" : "BSD-3-Clause",
   "repository" : {
      "type" : "git",
      "url" : "github:mulle-c/mulle-buffer"
   },
   "dependencies" : {
      "mulle-allocator" : "git://github.com/mulle-c/mulle-allocator",
      "mulle-c11" : "git://github.com/mulle-c/mulle-c11",
      "mulle-data" : "git://github.com/mulle-c/mulle-data",
      "src/farmhash-c" : "964E1DD0-08BA-4944-B09F-9CBD876383A4"
   }
}

mulle-project-clib-json produces clib compatible clib.json output:

{
   "name" : "mulle-buffer",
   "version" : "3.3.0",
   "description" : "A growable C char array and also a stream",
   "keywords" : [],
   "license" : "BSD-3-Clause",
   "repo" : "mulle-c/mulle-buffer",
   "src" : [
      "src/generic/include-private.h",
      "src/generic/include.h",
      "src/mulle--buffer.c",
      "src/mulle--buffer.h",
      "src/mulle-buffer-standalone.c",
      "src/mulle-buffer.c",
      "src/mulle-buffer.h",
      "src/mulle-flexbuffer.h",
      "src/reflect/_mulle-buffer-include-private.h",
      "src/reflect/_mulle-buffer-include.h",
      "src/reflect/_mulle-buffer-versioncheck.h"
   ],
   "dependencies" : {
      "mulle-c/mulle-allocator": "*",
      "mulle-c/mulle-data": "*"
   }
}