CMTools/approach_and_implementation.html at main · caltechlibrary/CMTools · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
<!DOCTYPE html>
<html lang="en-US">
<head>
    <title>CMTools</title>
    <link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
    <link rel="stylesheet" href="https://media.library.caltech.edu/cl-webcomponents/css/code-blocks.css">
    <script type="module" src="https://media.library.caltech.edu/cl-webcomponents/copyToClipboard.js"></script>
    <script type="module" src="https://media.library.caltech.edu/cl-webcomponents/footer-global.js"></script>
</head>
<body>
<header>
<a href="https://library.caltech.edu"><img src="https://media.library.caltech.edu/assets/caltechlibrary-logo.png" alt="Caltech Library logo"></a>
</header>
<a href="#main-content" class="visually-hidden">skip to main content</a>
<nav>
<ul>
    <li><a href="/">All Library Apps</a></li>
    <li><a href="index.html">Home</a></li>
    <li><a href="LICENSE">LICENSE</a></li>
    <li><a href="INSTALL.html">INSTALL</a></li>
    <li><a href="user_manual.html">User Manual</a></li>
    <li><a href="about.html">About</a></li>
    <!-- <li><a href="search.html">Search</a></li> -->
    <li><a href="https://github.com/caltechlibrary/CMTools">Code Repository</a></li>
</ul>
</nav>
<section id="main-content">
<h1 id="why-codemeta-tools">Why CodeMeta Tools?</h1>
<p>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.</p>
<p>Why is this significant? The metadata held in our CodeMeta file is
very helpful when integrating into software repositories like <a
href="https://data.caltech.edu">CaltechDATA</a>. 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.</p>
<h1 id="what-problem-am-i-solving-with-cmtools">What problem am I
solving with CMTools?</h1>
<p>The following files are common in my projects and other’s projects at
Caltech Library.</p>
<ul>
<li>CITATION.cff</li>
<li>about.md</li>
<li>version.go, version.py, version.js or version.ts</li>
<li>page templates for the project website</li>
<li>installer scripts for macOS, Linux and Windows</li>
</ul>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h1 id="implementation">Implementation</h1>
<p>CMTools is implemented as a <a
href="https://typescriptlang.org">TypeScript</a> program compiled using
<a href="https://deno.com">Deno</a>. Both <code>cme</code> and
<code>cmt</code> 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.</p>
<p>The architecture of CMTools is a series of small TypeScript files</p>
<p>codemeta.ts : provides the basic CodeMeta 3 object.</p>
<p>gitcmds.ts : provides a thin wrapper around the Git command for
retrieving Git hash values</p>
<p>helptext.ts : provides the help documentation use to generate man
pages and website doc pages</p>
<p>version.ts : This is generated by CMTools’ <code>cmt</code> command
and holds the version info for CMTools</p>
<p>person_or_organization.ts : This holds the agent model for people and
organizations used in the CodeMeta object</p>
<p>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 <code>generate_text.ts</code>.</p>
<p>generate_text.ts : This file holds the specific file content to be
generated.</p>
<p>cmt.ts : This is the TypeScript that provides our command line
interface for generating files based on codemeta.json</p>
<p>cme.ts : This is the TypeScript the provides our command line
interface for editing codemeta.json</p>
<p>editor.ts : This is used by <code>cme.ts</code> to provide an
interactive editor (E.g. nano, notepad, textedit)</p>
<p>person_or_organization.ts : This provides an class implementing the
codemeta.json person or organizational scheme</p>
<p>colors.ts : This provides some standard colorization of the cli.</p>
</section>
<footer-global></footer-global>
</body>
</html>