CMTools/using_cmtools.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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
<!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>
<nav>
<ul>
    <li><a href="/">Home</a></li>
    <li><a href="index.html">README</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">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="using-cmtools">Using CMTools</h1>
<p>What is CMTools? Two programs designed to work with a <a
href="https://codemeta.github.io">CodeMeta</a> file. One manages
curation the is a text/code generator based on the contents of your
CodeMeta file. The two save you time and effort setting up or
maintaining a GitHub based project. They were developed for Caltech
Library Digital Library Development Group as a alternative to using
GitHub template repositories.</p>
<p>The CodeMeta file is a JSON document that hold metadata about your
project (e.g. name, description, authorship, dates). When combined with
the metadata available from Git and your LICENSE file many files
typically included in a project can be generated automatically. This
means many of the software artifacts can be calculated as needed when
your metadata changes.</p>
<p>Here’s a brief list</p>
<ul>
<li>README.md</li>
<li>about.md</li>
<li>search.md</li>
<li>INSTALL.md
<ul>
<li>INSTALL_NOTES_macOS.md</li>
<li>INSTALL_NOTES_Windows.md</li>
</ul></li>
<li>CITATION.cff</li>
<li>Makefile, build.ps1</li>
<li>website.mak, website.ps1</li>
<li>installer.sh, installer.ps1</li>
<li>release.bash, release.ps1</li>
<li>publish.bash, publish.ps1</li>
<li>page.tmpl, page.hbs</li>
<li>version.py, version.go, version.js and version.ts</li>
</ul>
<p>The editing tool, <code>cme</code>, runs in your favorite shell
(e.g. Terminal, Bash, PowerShell) and will use the default shell’s text
editor for editing CodeMeta values.</p>
<p>To generate text or code you use <code>cmt</code>. All supported
files contain some level of the metadata captured in the <a
href="codemeta.json">codemeta.json</a>. Some also require information
from the Git repository’s <code>.git</code> directory and they need to
find a file called LICENSE that includes the text of your license.</p>
<h2 id="creating-and-maintaining-your-codemeta.json">creating and
maintaining your codemeta.json</h2>
<p>The tool for creating and maintaining your codemeta.json file is
called <code>cme</code>. That stands for “CodeMeta Editor”. It is an
interactive tool that will prompt for top level CodeMeta attributes and
let you enter them. It includes a <code>-e</code> option that will let
you update the value in your chosen editor. This is nice for longer
fields like <code>description</code> and <code>releaseNotes</code> as
well as complex fields like <code>author</code>,
<code>contributor</code>, <code>maintainer</code> and
<code>softwareRequirements</code>.</p>
<p>Complex fields are entered using <a
href="https://en.wikipedia.org/wiki/YAML">YAML</a> notation to describe
the element and attributes defined by the CodeMeta standard.</p>
<h2 id="generating-project-files-and-artifacts">generating project files
and artifacts</h2>
<p>Once you have a “codemeta.json” file you can use the tool named
<code>cmt</code>, “CodeMeta Transformer”, to transform the CodeMeta
contents into one or more files (see previous list). The CodeMeta JSON
file functions as the source of truth about the project. That means you
can generate initial versions of the files and continue hand editing
them or when are happy with the basics generate and regenerated as
needed when the CodeMeta JSON file changes.</p>
<h2 id="example-creating-a-deno-typescript-project">Example creating a
Deno TypeScript project</h2>
<p>In the following example I step through creating a “Hello World”
Deno+TypeScript project. A few things need to be in place before you can
use CMTools and generated files.</p>
<ol type="1">
<li>Create a Git repository directory</li>
<li>Change into that directory and initialize a new Git repository</li>
<li>Create a LICENSE (or just an empty placeholder)</li>
<li>Create the codemeta.json file using <code>cme</code></li>
<li>Generate the files for the project</li>
</ol>
<p>Steps one through three are the pre-CMTools setup. For steps four and
five you use CMTools’ programs.</p>
<pre class="shell"><code>mkdir -p src/helloworld
cd src/helloworld
touch LICENSE .gitignore
git init -am &#39;Initial Setup&#39;</code></pre>
<p>Now you’re ready to create your codemeta.json file. I’m using the
<code>-e</code> option so that I can edit the values in my preferred
text editor.</p>
<pre class="shell"><code>export EDITOR=&quot;nano&quot;
cme codemeta.json -e</code></pre>
<p>Now we are ready to generate files. The first time you run this.
You’ll likely get an error like</p>
<pre class="error"><code>&quot;git log --pretty=format:%h -n 1&quot; exited with 128
&quot;git config --get remote.origin.url&quot; exited with 1</code></pre>
<p>This is because we haven’t committed and pushed our repository
before. There are not any version numbers associated with the Git
log.</p>
<pre class="shell"><code>cmt codemeta.json README.md
cmt codemeta.json about.md
cmt codemeta.json INSTALL.md
cmt codemeta.json CITATION.cff
cmt codemeta.json Makefile --lang=TypeScript
cmt codemeta.json website.mak
cmt codemeta.json installer.sh
cmt codemeta.json installer.ps1
cmt codemeta.json release.bash
cmt codemeta.json publish.bash
cmt codemeta.json page.tmpl
cmt codemeta.json version.ts</code></pre>
<p>Add these files to the Git repository.</p>
<pre class="shell"><code>git add codemeta.json
git add README.md
git add about.md
git add INSTALL.md
git add CITATION.cff
git add Makefile
git add website.mak
git add installer.sh
git add installer.ps1
git add release.bash
git add publish.bash
git add page.tmpl
git add version.ts
git commit -am &#39;Initial Setup&#39;
git push -u origin main</code></pre>
<p>Now you’re ready to start development. Remember you can always update
these generated files by updating the codemeta.json file with
<code>cme</code> and then updating the files using <code>cmt</code>.</p>
</section>
<footer-global></footer-global>
</body>
</html>