forked from lda/telodendria
Begin documenting the build script.
This commit is contained in:
parent
6e4ff64d08
commit
5da3b9f983
1 changed files with 62 additions and 10 deletions
|
@ -598,7 +598,57 @@ I'll likely run my <code>indent(1)</code> on the code anyway though,
|
||||||
just to make sure the spacing is consistent, if nothing else.
|
just to make sure the spacing is consistent, if nothing else.
|
||||||
</p>
|
</p>
|
||||||
<h4 id="the-build-script">The Build Script</h4>
|
<h4 id="the-build-script">The Build Script</h4>
|
||||||
<!-- describe recipes and the .env file -->
|
<p>
|
||||||
|
<b>Telodendria</b> uses a custom build script called <code>td</code>,
|
||||||
|
for <i>Telodendria developer</i>. The <code>td</code> is not only
|
||||||
|
a build script, however. It does all kinds of cool things like
|
||||||
|
format the source code, and generate patch files. <code>td</code> is
|
||||||
|
the only supported way to build <b>Telodendria</b>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
I opted to write a custom build script instead of just using
|
||||||
|
<code>make</code>, because I felt that there is really no way to make
|
||||||
|
a truly portable <code>Makefile</code> that could do everything I
|
||||||
|
need. I was doing a lot of research on the differences between the
|
||||||
|
GNU and BSD versions of <code>make</code>, and I felt it just wasn't
|
||||||
|
worth it when I could write a small POSIX script that would run on
|
||||||
|
both GNU systems and BSD systems without a fuss. I also wanted a way
|
||||||
|
to automate more than just building code. I wanted a system
|
||||||
|
versatile enough that I could define arbitrary recipes to do whatever
|
||||||
|
I want. I didn't want to be limited by the <code>Makefile</code>
|
||||||
|
syntax.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>td</code> script is fairly intuitive. It operates somewhat
|
||||||
|
like <code>make</code>, in that it has recipes that you specify
|
||||||
|
on the command line. To start using it, just run the following
|
||||||
|
command in your <b>Telodendria</b> directory:
|
||||||
|
</p>
|
||||||
|
<div class="code">
|
||||||
|
$ . contrib/td-env.sh
|
||||||
|
</div>
|
||||||
|
<p>
|
||||||
|
<b>Note:</b> You will have to run the above command every time you
|
||||||
|
start a new terminal session, as nothing is persisted.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If you're going to be submitting patches, you should also configure
|
||||||
|
a <code>.env</code> file, which <code>td</code> will include
|
||||||
|
automatically for you. For the best experience, you'll want at
|
||||||
|
least these values:
|
||||||
|
</p>
|
||||||
|
<div class="code">
|
||||||
|
MXID=@your:matrix-id.net
|
||||||
|
DISPLAY_NAME="Your Display Name"
|
||||||
|
EDITOR=gedit # Or whatever your preferred editor is.
|
||||||
|
</div>
|
||||||
|
<p>
|
||||||
|
If you don't provide these values, <code>td</code> will deduce them
|
||||||
|
from your environment. It uses your system username and hostname to
|
||||||
|
create the <code>MXID</code>, and reads the password database to
|
||||||
|
get your configured display name. It also uses <code>vi</code> as
|
||||||
|
the default editor, which may not be suitable for all developers.
|
||||||
|
</p>
|
||||||
<h4 id="submitting-patches">Submitting Patches</h4>
|
<h4 id="submitting-patches">Submitting Patches</h4>
|
||||||
<p>
|
<p>
|
||||||
<b>Telodendria</b> aims at remaining as minimal as possible. This doesn't
|
<b>Telodendria</b> aims at remaining as minimal as possible. This doesn't
|
||||||
|
@ -614,35 +664,37 @@ opening a "pull request," you should be pleased to hear that submitting
|
||||||
patches is fairly easy to do if you've got the CVS sources checked out.
|
patches is fairly easy to do if you've got the CVS sources checked out.
|
||||||
In fact, I find it easier than having to make a GitHub account, forking
|
In fact, I find it easier than having to make a GitHub account, forking
|
||||||
a project repository, and then making a pull request for it. Once you
|
a project repository, and then making a pull request for it. Once you
|
||||||
have made your changes in your local copy of the code, just run the
|
have made your changes in your local copy of the code, and you've
|
||||||
|
configured your environment using the instructions in
|
||||||
|
<a href="#the-build-script">The Build Script</a>, just run the
|
||||||
<code>patch</code> recipe:
|
<code>patch</code> recipe:
|
||||||
</p>
|
</p>
|
||||||
<div class="code">
|
<div class="code">
|
||||||
$ sh make.sh patch
|
$ td patch
|
||||||
</div>
|
</div>
|
||||||
<p>
|
<p>
|
||||||
This will automatically generate the patch file from all your changes,
|
This will automatically generate a patch file for all your changes,
|
||||||
and then open it in your default editor. You can set the
|
and then open it in your default editor. You can set the
|
||||||
<code>EDITOR</code> variable to your preferred editor if the default
|
<code>EDITOR</code> variable to your preferred editor if the default
|
||||||
doesn't work for you. Either set it in your environment via your
|
doesn't work for you. Either set it in your environment via your
|
||||||
preferred means, or set it like this:
|
preferred means, or set it like this:
|
||||||
</p>
|
</p>
|
||||||
<div class="code">
|
<div class="code">
|
||||||
$ EDITOR=gedit sh make.sh patch
|
$ EDITOR=gedit td patch
|
||||||
</div>
|
</div>
|
||||||
<p>
|
<p>
|
||||||
You can also generate a patch for only certain files and directories.
|
You can also generate a patch for only certain files and directories.
|
||||||
To do that, set <code>PATCH</code>, like this:
|
To do that, set <code>PATCHSET</code>, like this:
|
||||||
</p>
|
</p>
|
||||||
<div class="code">
|
<div class="code">
|
||||||
# Only write a patch for README.txt and the files in site/
|
# Only write a patch for README.txt and the files in site/
|
||||||
$ PATCH="README.txt site/" sh make.sh patch
|
$ PATCHSET="README.txt site/" td patch
|
||||||
</div>
|
</div>
|
||||||
<p>
|
<p>
|
||||||
You can of course specify both <code>PATCH</code> and
|
You can of course specify both <code>PATCHSET</code> and
|
||||||
<code>EDITOR</code> at the same time, if you want. But at that point,
|
<code>EDITOR</code> at the same time, if you want. But at that point,
|
||||||
it might make more sense to just set them in <code>.env</code> or in
|
it might make more sense to just <code>EDITOR</code> in your
|
||||||
your system environment.
|
<code>.env</code> or in your system environment.
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
As you'll notice, the top of the patch file should have some email-style
|
As you'll notice, the top of the patch file should have some email-style
|
||||||
|
|
Loading…
Reference in a new issue