Over the last several years I’ve folded the codemeta.json file into my development and build processes for releasing software at Caltech Library. Initially I used a tool I wrote called “codemeta2cff”. It did one thing which was create a CITATION.cff from the codemeta.json file. Over time I wound up re-using the idea to generation version files for Go, Python, JavaScript and TypeScript projects. Then I added generation of installation scripts and the “about.md”. The various scripts and Pandoc templates became pretty unwieldy and that lead to thinking about a more holistic approach. That lead to CMTools.
Why is this significant? The metadata held in our CodeMeta file is very helpful when integrating into software repositories like CaltechDATA. While my initial focus in adopting CodeMeta was documentation for my projects I think it can play a common role across projects regardless of implementation language. On the command line this means you can easily have a consistent “version” response indicating not just the semver and program name but also the Git hash and compile date. This is important for support reasons. As we evolve programs that are deployed on individual computers users often don’t update their software. Knowing that they are running a different version than the currently supported one can cut down the time needed to diagnosis issues. Similarly if we introduce a regression in a new version we can check to see if the fix got applied because the Git hash in the version string will change on each commit. For server software having consistent version info serves a similar role.
The following files are common in my projects and other’s projects at Caltech Library.
Having a CMTool that can generate these means the build processes can be simplified and can more easily translate across the POSIX and Windows divide.
The common files that can use the information in the CodeMeta file are likely to grow over time. The implementation of CMTools should make it easy to add additional transformations as needed.
Prior to CMTools my build processes required Pandoc. Pandoc isn’t something that most developers think about as part of their build tool chain outside of building websites. With an easy to install command line tool the Pandoc dependency can be removed. I still use Pandoc to render CommonMark documentation to HTML but that isn’t required if you just want to compile from source code.
CMTools is implemented as a TypeScript program compiled using
Deno. Both cme and
cmt are a static executables and can be “installed” with a
simple copy command. TypeScript was chosen because it is a superset of
JavaScript which is one of the most common programming languages in the
early 21st century. This is the type of tool that will benefit from
community contributions. Deno provide easy cross platform compilation
for our supported operating systems – macOS, Windows and Linux. Deno and
TypeScript together provide many of the advantages of our Go based
utilities with the advantage of a large part of the Library, Archives
and Museum developer communities that could potentially contribute.
The architecture of CMTools is a series of small TypeScript files
codemeta.ts : provides the basic CodeMeta 3 object.
gitcmds.ts : provides a thin wrapper around the Git command for retrieving Git hash values
helptext.ts : provides the help documentation use to generate man pages and website doc pages
version.ts : This is generated by CMTools’ cmt command
and holds the version info for CMTools
person_or_organization.ts : This holds the agent model for people and organizations used in the CodeMeta object
transform.ts : This does the heavy lifting and transforming the
CodeMeta 3 object into our target files. It holds the functions for the
transform as well as the mappings of variables to text. The texts are in
the file generate_text.ts.
generate_text.ts : This file holds the specific file content to be generated.
cmt.ts : This is the TypeScript that provides our command line interface for generating files based on codemeta.json
cme.ts : This is the TypeScript the provides our command line interface for editing codemeta.json
editor.ts : This is used by cme.ts to provide an
interactive editor (E.g. nano, notepad, textedit)
person_or_organization.ts : This provides an class implementing the codemeta.json person or organizational scheme
colors.ts : This provides some standard colorization of the cli.