mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More details in guidelines

Browse Source 
This includes updates from a recent change in txzchk and more details
about the tools and what they check (warnings and errors) and how to use
them individually.

This does need to be reviewed further, possibly being shorted or
referring to an FAQ, but it's a good start.

The rules had a typo fix as well.
This commit is contained in:
Cody Boone Ferguson committed 2024-07-11 14:35:38 -07:00
1 parent 61495bd46e
commit f94c324c31
4 files changed
+526 -284
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

next/guidelines.html
+266 -129
View File
@@ -416,7 +416,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
<h2 id="ioccc-guidelines-version">IOCCC Guidelines version</h2> <h2 id="ioccc-guidelines-version">IOCCC Guidelines version</h2>
</div> </div>
<p class="leftbar"> <p class="leftbar">
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.8 2024-07-10</strong>. These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.9 2024-07-11</strong>.
</p> </p>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p> <p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<div id="change_marks"> <div id="change_marks">
@@ -602,11 +602,11 @@ The overall size limit (see <a href="rules.html#rule2a">Rule 2a</a>) on <code>pr
</p> </p>
<p class="leftbar"> <p class="leftbar">
Your submission must satisfy BOTH the maximum size <a href="rules.html#rule2a">Rule Your submission must satisfy BOTH the maximum size <a href="rules.html#rule2a">Rule
2a</a> AND the IOCCC size tool <a href="rules.html#rule2b">Rule 2b</a>. 2a</a> <strong>AND</strong> the IOCCC size tool <a href="rules.html#rule2b">Rule 2b</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
This IOCCC size tool imposes a 2nd limit on C code size (see <a href="rules.html#rule2a">Rule 2a</a>. To check your This IOCCC size tool imposes a 2nd limit on C code size (see <a href="rules.html#rule2a">Rule
code against <a href="rules.html#rule2">Rule 2</a>: 2a</a>). To check your code against <a href="rules.html#rule2">Rule 2</a>:
</p> </p>
<pre><code> iocccsize prog.c</code></pre> <pre><code> iocccsize prog.c</code></pre>
<p>The IOCCC size tool algorithm may be summarized as follows:</p> <p>The IOCCC size tool algorithm may be summarized as follows:</p>
@@ -621,7 +621,7 @@ before the end of file.</p>
ASCII formfeed, and ASCII carriage return.</p> ASCII formfeed, and ASCII carriage return.</p>
<p class="leftbar"> <p class="leftbar">
When ‘<code>;</code>’, ‘<code>{</code>’ or ‘<code>}</code>’ are within a C string, they may still not be When ‘<code>;</code>’, ‘<code>{</code>’ or ‘<code>}</code>’ are within a C string, they may still not be
counted by the IOCCC size tool. This is a feature, not a bug! counted by the IOCCC size tool. This is a <em>feature</em>, not a bug!
</p> </p>
<p>In cases where the above summary and the algorithm implemented by <p>In cases where the above summary and the algorithm implemented by
the IOCCC size tool source code conflict, the algorithm implemented the IOCCC size tool source code conflict, the algorithm implemented
@@ -643,25 +643,60 @@ The <a href="rules.html#rule2a">Rule 2a</a> size was changed from
value similar to the <a href="../faq.html#size_rule2001-2012">2001-2012</a> and value similar to the <a href="../faq.html#size_rule2001-2012">2001-2012</a> and
<a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras. <a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras.
</p> </p>
<h2 id="mkiocccentry"><code>mkiocccentry</code></h2>
<p class="leftbar"> <p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> (the <code>mkiocccentry(1)</code> rule) states that <a href="rules.html#rule17">Rule 17</a> (the <code>mkiocccentry(1)</code> rule) states that
you <strong>MUST</strong> use the <code>mkiocccentry(1)</code> tool to package your submission tarball. you <strong>MUST</strong> use the <code>mkiocccentry(1)</code> tool to package your submission tarball.
</p> </p>
<p class="leftbar"> <p class="leftbar">
See the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> See the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
for the <code>mkiocccentry(1)</code> tool. for the <code>mkiocccentry(1)</code> tool and below for more details.
</p> </p>
<p class="leftbar"> <p class="leftbar">
This tool invokes a number of other tools and one, <code>txzchk(1)</code>, <code>mkiocccentry</code> runs a number of checks, by the tool itself and by executing other
invokes another, <code>fnamchk(1)</code>. tools, <em>before</em> packaging your xz compressed tarball. Once the tarball is
packaged it will run <code>txzchk(1)</code>, which runs <code>fnamchk(1)</code> as part of its
algorithm.
</p> </p>
<p class="leftbar"> <p class="leftbar">
Although the <code>mkiocccentry(1)</code> tool will verify everything for you, If <code>mkiocccentry</code> encounters an <strong>error</strong> the program will exit and the xz
you may wish to validate each part individually. As the <a href="rules.html">rules</a> compressed tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> (see
state, each of these tools have a <code>-h</code> option. However, to help simplify below) fails to validate the <code>.auth.json</code> or <code>.info.json</code>
matters, we give you a brief overview below. <a href="https://www.json.org/json-en.html">JSON</a> files that <code>mkiocccentry(1)</code> creates,
it is an error and possibly a bug that you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report as a bug at the
mkiocccentry issues
page</a>.
<strong>PLEASE run the <code>bug_report.sh</code> script to help us out here!</strong> See the <a href="../faq.html#mkiocccentry_bugs">the FAQ
about reporting bugs in the mkiocccentry repo</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
However, just because there are errors <strong>does not</strong> mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there might not be
anything wrong.
</p>
<p class="leftbar">
On the other hand, some conditions are <strong>warnings</strong> and it allows you to
override these, if you wish. If you’re brave enough you can use the <code>-W</code> option
to ignore all warnings but this is a big risk; the <code>-y</code> option will assume
‘<em>yes</em>’ to most questions but this is also a big risk. Needless to say, we do
NOT recommend these options.
</p>
<p class="leftbar">
In many places it will prompt you to verify what you input, allowing you to
correct details as you go along.
</p>
<p class="leftbar">
Although the <code>mkiocccentry(1)</code> tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
<a href="rules.html">rules</a> state, each of these tools has a <code>-h</code> option. However, to
help simplify matters, we give you a brief overview below, which should also
help you understand some of the checks the tool makes.
</p>
<div id="mkiocccentry-synopsis">
<h2 id="mkiocccentry1-synopsis"><code>mkiocccentry(1)</code> synopsis</h2>
</div>
<p class="leftbar">
The synopsis of the <code>mkiocccentry(1)</code> tool is: The synopsis of the <code>mkiocccentry(1)</code> tool is:
</p> </p>
<pre><code> mkiocccentry [options] work_dir prog.c \ <pre><code> mkiocccentry [options] work_dir prog.c \
@@ -670,7 +705,7 @@ The synopsis of the <code>mkiocccentry(1)</code> tool is:
… where <code>work_dir</code> is a directory that will be used to build the submission … where <code>work_dir</code> is a directory that will be used to build the submission
tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s tarball, <code>prog.c</code> is your submission source code, <code>Makefile</code> is your submission’s
<code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the <code>Makefile</code>, <code>remarks.md</code> are your remarks (that will be the basis of the
<code>README.md</code> file which will be used to form the <code>index.html</code> file if your <code>README.md</code> file which will be used to form the <code>index.html</code> file, if your
submission wins) and the remaining args are the paths to any other files you submission wins) and the remaining args are the paths to any other files you
wish to submit. wish to submit.
</p> </p>
@@ -680,96 +715,32 @@ the requirements of these files.
</p> </p>
<p class="leftbar"> <p class="leftbar">
The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it The <code>work_dir</code> <strong>MUST</strong> already exist, as a directory, and it is an error if it
is not a directory that can be written to. In this directory your submission is not a directory that can be written to. In <strong>this</strong> directory your <strong>submission
directory will be created, with the name based on your IOCCC registration directory</strong> will be created, with the name based on your IOCCC registration
username <strong>in the form of a UUID</strong> and submission number; see the username, which is <strong>in the form of a UUID</strong> and submission number; see the
<a href="rules.html">rules</a> for more details on this, and in particular <a href="rules.html#rule17">Rule <a href="rules.html">rules</a> for more details on this, and in particular <a href="rules.html#rule17">Rule
17</a>. 17</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
If the subdirectory in the work directory already exists, you will have to move If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> already exists, you will have to
it or remove it or otherwise specify a different work directory as it needs to move it, remove it or otherwise specify a different work directory (<strong>NOT</strong>
be empty and the <code>mkiocccentry(1)</code> tool does not check this for you subdirectory), as it needs to be empty and the <code>mkiocccentry(1)</code> tool does not
as it could do nothing about anyway. This subdirectory is where your files will be check this for you as it could not do anything about anyway. This <em>subdirectory is
<strong>copied</strong> to. Your submission tarball (which you will upload to the submit where your files will be <strong>copied</strong> to</em>. Your <em>submission tarball</em> (which you will
server) that <code>txzchk(1)</code> will validate will be placed in the work directory, and upload to the submit server) that <code>txzchk(1)</code> will validate <em>will be placed in
its contents will be the subdirectory with your submission’s files. the <strong>work directory</strong></em>, and <strong>its <em>contents</em> will be the <em>subdirectory</em> with your
submission’s files</strong>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
The <code>mkiocccentry(1)</code> tool will ask you for information about your The <code>mkiocccentry(1)</code> tool will ask you for information about your
submission as well as author details and it will run the <code>iocccsize(1)</code> tool; if submission <em>as well as author details</em> (that will only be looked at if the
either <a href="rules.html#rule2a">Rule 2a</a> or <a href="rules.html#rule2b">Rule 2b</a> are broken, submission wins), run some tests and run a number of other tools, as already
it will give you the option to ignore them, if you are willing to risk this. mentioned and as described below.
</p>
<p class="leftbar">
The tool will also do a rudimentary check on the <code>Makefile</code> and run other checks as
well. You can override warnings as well but doing so puts you at risk of
violating the <a href="rules.html">rules</a>.
</p>
<p class="leftbar">
If you’re brave you can use the <code>-W</code> option to ignore all warnings but this is a
big risk; the <code>-y</code> option will assume ‘<em>yes</em>’ to most questions but this is also a
big risk.
</p>
<p class="leftbar">
On the other hand, some <strong>issues are an error</strong> and the xz compressed
tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> fails to validate
the <code>.auth.json</code> or <code>.info.json</code> <a href="https://www.json.org/json-en.html">JSON</a> files
that <code>mkiocccentry(1)</code> creates, it is an error and possibly a bug that you
should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report as a bug at the mkiocccentry issues
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
bugs in the mkiocccentry repo</a>.
</p>
<p class="leftbar">
However, just because there are errors <strong>does not</strong> mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there is nothing to be
fixed in the first place.
</p>
<p class="leftbar">
Assuming that <code>chkentry(1)</code> validates both <code>.auth.json</code> and
<code>.info.json</code> then the tarball will be formed and then <code>txzchk(1)</code> will be
executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> should
<strong>NOT</strong> form a tarball if there are any issues. If there is an issue reported,
however, this is possibly a bug in one or more of the tools and you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report
it as a bug at the mkiocccentry issues
page</a>.
See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
bugs in the mkiocccentry repo</a>.
</p>
<p class="leftbar">
<code>txzchk(1)</code> performs a wide number of sanity checks on the xz
compressed tarball; if any issues are found (‘<code>feathers are stuck in the tarball</code>’ :-) ) <strong>AND if and <em>ONLY IF</em> you used
<code>mkiocccentry(1)</code></strong>, then it is very possibly a bug in one of the tools and you
should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs
in the mkiocccentry repo</a>.
</p>
<p class="leftbar">
As part of its sanity checks, <code>txzchk(1)</code> will run <code>fnamchk(1)</code> on the
<em>filename</em> to verify that the name is valid.
</p>
<p class="leftbar">
It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a
bug in <code>fnamchk(1)</code> and as such, ignoring such an issue risks violating <a href="rules.html#rule17">Rule
17</a> which is a big risk. Of course, using <code>mkiocccentry(1)</code>
would prevent this from happening as it would not create such a file anyway. If
<code>mkiocccentry(1)</code> was used it would rather suggest a bug in one of the tools and
you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
page</a>.
See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs in the mkiocccentry
repo</a>.
</p>
<p class="leftbar">
By default, <code>txzchk(1)</code> will show the contents of the tarball which is
how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to review.
</p> </p>
<p class="leftbar"> <p class="leftbar">
To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has To help you with editing a submission, the <code>mkiocccentry(1)</code> tool has
some options to write <em>OR</em> read from an answers file so you do not have to input some options to write <em>OR</em> read from an answers file so you do not have to input
the information about the author(s) and the entry itself after saving the the information about the author(s) and the submission itself, after saving the
answers to a file. To write to <code>answers.txt</code> try: answers to a file. To write to <code>answers.txt</code> try:
</p> </p>
<pre><code> mkiocccentry -a answers.txt ...</code></pre> <pre><code> mkiocccentry -a answers.txt ...</code></pre>
@@ -782,50 +753,152 @@ overwrite your <code>prog.c</code> or some other important file!
To make use of the answers file, use the <code>-i answers</code> option like: To make use of the answers file, use the <code>-i answers</code> option like:
</p> </p>
<pre><code> mkiocccentry -i answers.txt ...</code></pre> <pre><code> mkiocccentry -i answers.txt ...</code></pre>
<h3 id="mkiocccentry-checks"><code>mkiocccentry</code> checks</h3>
<p class="leftbar"> <p class="leftbar">
If you wish to manually run the commands that <code>mkiocccentry(1)</code> runs, to test <code>mkiocccentry(1)</code> will check and warn about the following conditions:
your submission, you can do so. For instance, to check the validity of the
tarball <code>submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code> you can
do:
</p> </p>
<pre><code> txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre> <ul>
<li><p class="leftbar">
if the files do not exist, are not regular files or cannot be read.
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> violates <a href="rules.html#rule2">Rule 2</a> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> is empty.
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> has any high bit char (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> has any NUL char (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> has any unknown or invalid trigraph (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> triggers a word buffer overflow (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if <code>prog.c</code> triggers an <code>ungetc(3)</code> error (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).
</p></li>
<li><p class="leftbar">
if the first rule in the <code>Makefile</code> is not <code>all</code>.
</p></li>
<li><p class="leftbar">
if the <code>Makefile</code> does not have a <code>clean</code> rule.
</p></li>
<li><p class="leftbar">
if the <code>Makefile</code> does not have a <code>clobber</code> rule.
</p></li>
<li><p class="leftbar">
if the <code>Makefile</code> does not have a <code>try</code> rule.
</p></li>
<li><p class="leftbar">
if the <code>remarks.md</code> is empty.
</p></li>
</ul>
<p class="leftbar"> <p class="leftbar">
Assuming that the tarball exists and is valid, you should see the Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
contents of the tarball, along with a few other minor details, and the words: it is correct, are:
</p> </p>
<blockquote> <ul>
<p>No feathers stuck in tarball.</p> <li><p class="leftbar">
</blockquote> your <em>title</em> is not in the range of 1 through <code>MAX_TITLE_LEN</code> chars (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
your <em>title</em> does not match the regexp <code>^[0-9a-z][0-9a-z._+-]*$</code>.
</p></li>
<li><p class="leftbar">
your <em>abstract</em> is not between 1 and <code>MAX_ABSTRACT_LEN</code> chars
(see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
the author count is not 1 through <code>MAX_AUTHORS</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
an author <em>name</em> is not 1 through <code>MAX_NAME_LEN</code> chars (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
duplicate author <em>name</em>.
</p></li>
<li><p class="leftbar">
<em>country code</em> is invalid (not ISO 3166-1 2 character
codes).
</p></li>
<li><p class="leftbar">
an <em>email</em>, if provided, is not in the format of <code>x@y</code> or
if <code>x</code> or <code>y</code> contain a <code>@</code>, are empty or if the total length is longer than
<code>MAX_EMAIL_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
a <em>URL</em> or <em>alt URL</em>, if provided, does not start with <code>http://</code>
or <code>https://</code> or is longer than <code>MAX_URL_LEN</code> chars (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>)
or does not have anything after the <code>http://</code> or <code>https://</code>.
</p></li>
<li><p class="leftbar">
a <em>mastodon handle</em>, if provided, is not in the form of
<code>@user@site</code> (i.e. starts with an <code>@</code>, has text following it and then another
<code>@</code> followed by more text and has no other <code>@</code>) or is longer than <code>MAX_MASTODON_LEN</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
a <em>GitHub account</em>, if provided, does not start with an <code>@</code>,
has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
an <em>affiliation</em>, if provided, is longer than
<code>MAX_AFFILIATION_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).
</p></li>
<li><p class="leftbar">
an <em>author handle</em>, if the default is not accepted, does
not match the regexp <code>^[0-9A-Za-z][0-9A-Za-z._+-]*$</code>.
</p></li>
<li><p class="leftbar">
an <em>author handle</em> is repeated.
</p></li>
<li><p class="leftbar">
the output of <code>ls</code> on the submission directory is
incorrect.
</p></li>
</ul>
<p class="leftbar"> <p class="leftbar">
If you give the option <code>-q</code> it will not report anything unless there are certain Below are the tools that <code>mkiocccentry(1)</code> will run.
error conditions; issues (‘feathers’ :-) ) found in the tarball are not </p>
considered errors so that one can get an overview of all the issues in the <h2 id="iocccsize"><code>iocccsize</code></h2>
tarball but with <code>-q</code> these will not be reported unless <code>-w</code> is used (but as <p class="leftbar">
<code>-w</code> is meant for the test suite you do not need to concern yourself with that). <code>mkiocccentry(1)</code> will use code from <code>iocccsize(1)</code> which
Thus you should check the exit code if you use <code>-q</code>. detects a number of issues that you may ignore, if you wish, as described above.
As we already discussed how to invoke this we will not include it here again.
</p>
<h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar">
<code>mkiocccentry(1)</code> will write two JSON files: <code>.auth.json</code> and
<code>.info.json</code>. These files contain information about the author(s) and about the
submission. These files <strong>MUST</strong> pass the checks of <code>chkentry(1)</code>. If it does
not pass and you used <code>mkiocccentry(1)</code> it is very possibly a bug and you should
<a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report
it as a bug at the mkiocccentry issues
page</a>.
See the <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting
bugs in the mkiocccentry repo</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
For instance, the following command will not show anything unless there is a Assuming that <code>chkentry(1)</code> validates both <code>.auth.json</code> and
problem with the tarball, in which case it will show <code>Feathers stuck in tarball :-(</code>. <code>.info.json</code> then the tarball will be formed and then <code>txzchk(1)</code> will be
</p> executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> should
<pre><code> txzchk -q submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz || \ <strong>NOT</strong> form a tarball if there are any issues.
echo &#39;Feathers stuck in tarball :-(&#39;</code></pre>
<p class="leftbar">
Alternatively you could just check the exit code with <code>echo $?</code>; a value of 0
indicates all is OK.
</p>
<p class="leftbar">
If you wish to run <code>fnamchk(1)</code> directly you can do so like:
</p>
<pre><code> fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
<p class="leftbar">
Assuming everything is OK, it would show:
</p>
<blockquote>
<p><code>12345678-1234-4321-abcd-1234567890ab-2</code></p>
</blockquote>
<p class="leftbar">
… which, as stated earlier, <code>txzchk(1)</code> uses.
</p> </p>
<p class="leftbar"> <p class="leftbar">
If you want to validate the <code>.auth.json</code> or <code>.info.json</code> files you If you want to validate the <code>.auth.json</code> or <code>.info.json</code> files you
@@ -854,6 +927,70 @@ there <em>is an issue</em> in one or both of the
it will report this as an error</strong>. Thus, if you were to package this manually it will report this as an error</strong>. Thus, if you were to package this manually
then you would be violating <a href="rules.html#rule17">Rule 17</a>. then you would be violating <a href="rules.html#rule17">Rule 17</a>.
</p> </p>
<h2 id="txzchk"><code>txzchk</code></h2>
<p class="leftbar">
<code>txzchk(1)</code> performs a wide number of sanity checks on the xz
compressed tarball; if any issues are found (‘<code>feathers are stuck in the tarball</code>’ :-) ) <strong>AND if and <em>ONLY IF</em> you used
<code>mkiocccentry(1)</code></strong>, then it is very possibly a bug in one of the tools and you
should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs
in the mkiocccentry repo</a>.
</p>
<p class="leftbar">
As part of its sanity checks, <code>txzchk(1)</code> will run <code>fnamchk(1)</code> on the
<em>filename</em> to verify that the name is valid.
</p>
<p class="leftbar">
It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a
bug in <code>fnamchk(1)</code> and as such, ignoring such an issue risks violating <a href="rules.html#rule17">Rule
17</a> which is a big risk. Of course, using <code>mkiocccentry(1)</code>
would prevent this from happening as it would not create such a file anyway. If
<code>mkiocccentry(1)</code> was used it would rather suggest a bug in one of the tools and
you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
page</a>.
See <a href="../faq.html#mkiocccentry_bugs">the FAQ about reporting bugs in the mkiocccentry
repo</a>.
</p>
<p class="leftbar">
If verbosity level is &gt; 0, <code>txzchk(1)</code> will show the contents of the tarball which is
how the <code>mkiocccentry(1)</code> shows you the tarball contents for you to review.
</p>
<p class="leftbar">
It is beyond the scope of this document to discuss the many tests that
<code>txzchk(1)</code> do. In this case we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
code</a> or the man
page. You might find a fun option if you do either of these!
</p>
<p class="leftbar">
If you wish to validate the tarball without running the <code>mkiocccentry(1)</code> tool,
for instance the tarball <code>submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code> you can
do:
</p>
<pre><code> txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
<p class="leftbar">
Assuming that the tarball exists and is valid, you should see no output.
</p>
<p class="leftbar">
If you wish to see the contents, for instance like <code>mkiocccentry(1)</code> does, you
could do:
</p>
<pre><code> txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
<h2 id="fnamchk"><code>fnamchk</code></h2>
<p class="leftbar">
A tool that <a href="#txzchk">txzchk</a> runs is <code>fnamchk</code>. This is an important part of
its algorithm but if you wish to validate a submission filename you can do so:
</p>
<pre><code> fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz</code></pre>
<p class="leftbar">
Assuming everything is OK, it would show:
</p>
<blockquote>
<p><code>12345678-1234-4321-abcd-1234567890ab-2</code></p>
</blockquote>
<p class="leftbar">
… which, as stated earlier, <code>txzchk(1)</code> uses.
</p>
<p class="leftbar"> <p class="leftbar">
At the risk of stating the obvious: you run <strong>a very big risk</strong> of having At the risk of stating the obvious: you run <strong>a very big risk</strong> of having
your submission rejected if you package your own tarball and there are <strong>any your submission rejected if you package your own tarball and there are <strong>any
next/guidelines.md
+252 -149
View File
@@ -46,7 +46,7 @@ writing by [contacting the judges](../contact.html).
</div> </div>
<p class="leftbar"> <p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.8 2024-07-10**. These [IOCCC guidelines](guidelines.html) are version **28.9 2024-07-11**.
</p> </p>
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html). **IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -273,12 +273,12 @@ The overall size limit (see [Rule 2a](rules.html#rule2a)) on `prog.c` is now **4
<p class="leftbar"> <p class="leftbar">
Your submission must satisfy BOTH the maximum size [Rule Your submission must satisfy BOTH the maximum size [Rule
2a](rules.html#rule2a) AND the IOCCC size tool [Rule 2b](rules.html#rule2b). 2a](rules.html#rule2a) **AND** the IOCCC size tool [Rule 2b](rules.html#rule2b).
</p> </p>
<p class="leftbar"> <p class="leftbar">
This IOCCC size tool imposes a 2nd limit on C code size (see [Rule 2a](rules.html#rule2a). To check your This IOCCC size tool imposes a 2nd limit on C code size (see [Rule
code against [Rule 2](rules.html#rule2): 2a](rules.html#rule2a)). To check your code against [Rule 2](rules.html#rule2):
</p> </p>
``` <!---sh--> ``` <!---sh-->
@@ -298,7 +298,7 @@ ASCII formfeed, and ASCII carriage return.
<p class="leftbar"> <p class="leftbar">
When '`;`', '`{`' or '`}`' are within a C string, they may still not be When '`;`', '`{`' or '`}`' are within a C string, they may still not be
counted by the IOCCC size tool. This is a feature, not a bug!</p> counted by the IOCCC size tool. This is a _feature_, not a bug!</p>
In cases where the above summary and the algorithm implemented by In cases where the above summary and the algorithm implemented by
the IOCCC size tool source code conflict, the algorithm implemented the IOCCC size tool source code conflict, the algorithm implemented
@@ -325,6 +325,10 @@ value similar to the [2001-2012](../faq.html#size_rule2001-2012) and
[2013-2020](../faq.html#size_rule2013-2020) IOCCC eras. [2013-2020](../faq.html#size_rule2013-2020) IOCCC eras.
</p> </p>
<div id="mkiocccentry">
## `mkiocccentry`
</div>
<p class="leftbar"> <p class="leftbar">
[Rule 17](rules.html#rule17) (the `mkiocccentry(1)` rule) states that [Rule 17](rules.html#rule17) (the `mkiocccentry(1)` rule) states that
you **MUST** use the `mkiocccentry(1)` tool to package your submission tarball. you **MUST** use the `mkiocccentry(1)` tool to package your submission tarball.
@@ -332,21 +336,61 @@ you **MUST** use the `mkiocccentry(1)` tool to package your submission tarball.
<p class="leftbar"> <p class="leftbar">
See the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) See the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
for the `mkiocccentry(1)` tool. for the `mkiocccentry(1)` tool and below for more details.
</p> </p>
<p class="leftbar"> <p class="leftbar">
This tool invokes a number of other tools and one, `txzchk(1)`, `mkiocccentry` runs a number of checks, by the tool itself and by executing other
invokes another, `fnamchk(1)`. tools, _before_ packaging your xz compressed tarball. Once the tarball is
packaged it will run `txzchk(1)`, which runs `fnamchk(1)` as part of its
algorithm.
</p> </p>
<p class="leftbar"> <p class="leftbar">
Although the `mkiocccentry(1)` tool will verify everything for you, If `mkiocccentry` encounters an **error** the program will exit and the xz
you may wish to validate each part individually. As the [rules](rules.html) compressed tarball **will not be formed**. For instance, if `chkentry(1)` (see
state, each of these tools have a `-h` option. However, to help simplify below) fails to validate the `.auth.json` or `.info.json`
matters, we give you a brief overview below. [JSON](https://www.json.org/json-en.html) files that `mkiocccentry(1)` creates,
it is an error and possibly a bug that you should [report as a bug at the
mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
**PLEASE run the `bug_report.sh` script to help us out here!** See the [the FAQ
about reporting bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p> </p>
<p class="leftbar">
However, just because there are errors **does not** mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there might not be
anything wrong.
</p>
<p class="leftbar">
On the other hand, some conditions are **warnings** and it allows you to
override these, if you wish. If you're brave enough you can use the `-W` option
to ignore all warnings but this is a big risk; the `-y` option will assume
'_yes_' to most questions but this is also a big risk. Needless to say, we do
NOT recommend these options.
</p>
<p class="leftbar">
In many places it will prompt you to verify what you input, allowing you to
correct details as you go along.
</p>
<p class="leftbar">
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
[rules](rules.html) state, each of these tools has a `-h` option. However, to
help simplify matters, we give you a brief overview below, which should also
help you understand some of the checks the tool makes.
</p>
<div id="mkiocccentry-synopsis">
## `mkiocccentry(1)` synopsis
</div>
<p class="leftbar"> <p class="leftbar">
The synopsis of the `mkiocccentry(1)` tool is: The synopsis of the `mkiocccentry(1)` tool is:
</p> </p>
@@ -360,7 +404,7 @@ The synopsis of the `mkiocccentry(1)` tool is:
... where `work_dir` is a directory that will be used to build the submission ... where `work_dir` is a directory that will be used to build the submission
tarball, `prog.c` is your submission source code, `Makefile` is your submission's tarball, `prog.c` is your submission source code, `Makefile` is your submission's
`Makefile`, `remarks.md` are your remarks (that will be the basis of the `Makefile`, `remarks.md` are your remarks (that will be the basis of the
`README.md` file which will be used to form the `index.html` file if your `README.md` file which will be used to form the `index.html` file, if your
submission wins) and the remaining args are the paths to any other files you submission wins) and the remaining args are the paths to any other files you
wish to submit. wish to submit.
</p> </p>
@@ -372,109 +416,35 @@ the requirements of these files.
<p class="leftbar"> <p class="leftbar">
The `work_dir` **MUST** already exist, as a directory, and it is an error if it The `work_dir` **MUST** already exist, as a directory, and it is an error if it
is not a directory that can be written to. In this directory your submission is not a directory that can be written to. In **this** directory your **submission
directory will be created, with the name based on your IOCCC registration directory** will be created, with the name based on your IOCCC registration
username **in the form of a UUID** and submission number; see the username, which is **in the form of a UUID** and submission number; see the
[rules](rules.html) for more details on this, and in particular [Rule [rules](rules.html) for more details on this, and in particular [Rule
17](rules.html#rule17). 17](rules.html#rule17).
</p> </p>
<p class="leftbar"> <p class="leftbar">
If the subdirectory in the work directory already exists, you will have to move If the **_subdirectory_ in the _work directory_** already exists, you will have to
it or remove it or otherwise specify a different work directory as it needs to move it, remove it or otherwise specify a different work directory (**NOT**
be empty and the `mkiocccentry(1)` tool does not check this for you subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not
as it could do nothing about anyway. This subdirectory is where your files will be check this for you as it could not do anything about anyway. This _subdirectory is
**copied** to. Your submission tarball (which you will upload to the submit where your files will be **copied** to_. Your _submission tarball_ (which you will
server) that `txzchk(1)` will validate will be placed in the work directory, and upload to the submit server) that `txzchk(1)` will validate _will be placed in
its contents will be the subdirectory with your submission's files. the **work directory**_, and **its _contents_ will be the _subdirectory_ with your
submission's files**.
</p> </p>
<p class="leftbar"> <p class="leftbar">
The `mkiocccentry(1)` tool will ask you for information about your The `mkiocccentry(1)` tool will ask you for information about your
submission as well as author details and it will run the `iocccsize(1)` tool; if submission _as well as author details_ (that will only be looked at if the
either [Rule 2a](rules.html#rule2a) or [Rule 2b](rules.html#rule2b) are broken, submission wins), run some tests and run a number of other tools, as already
it will give you the option to ignore them, if you are willing to risk this. mentioned and as described below.
</p>
<p class="leftbar">
The tool will also do a rudimentary check on the `Makefile` and run other checks as
well. You can override warnings as well but doing so puts you at risk of
violating the [rules](rules.html).
</p>
<p class="leftbar">
If you're brave you can use the `-W` option to ignore all warnings but this is a
big risk; the `-y` option will assume '_yes_' to most questions but this is also a
big risk.
</p>
<p class="leftbar">
On the other hand, some **issues are an error** and the xz compressed
tarball **will not be formed**. For instance, if `chkentry(1)` fails to validate
the `.auth.json` or `.info.json` [JSON](https://www.json.org/json-en.html) files
that `mkiocccentry(1)` creates, it is an error and possibly a bug that you
should [report as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
`bug_report.sh` script to help us out here!** See the [the FAQ about reporting
bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
However, just because there are errors **does not** mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there is nothing to be
fixed in the first place.
</p>
<p class="leftbar">
Assuming that `chkentry(1)` validates both `.auth.json` and
`.info.json` then the tarball will be formed and then `txzchk(1)` will be
executed. In this case, there should be no problems as `mkiocccentry(1)` should
**NOT** form a tarball if there are any issues. If there is an issue reported,
however, this is possibly a bug in one or more of the tools and you should [report
it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
See the [the FAQ about reporting
bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
`txzchk(1)` performs a wide number of sanity checks on the xz
compressed tarball; if any issues are found ('`feathers are stuck in the
tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is very possibly a bug in one of the tools and you
should [report it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
`bug_report.sh` script to help us out here!** See [the FAQ about reporting bugs
in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the
_filename_ to verify that the name is valid.
</p>
<p class="leftbar">
It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a
bug in `fnamchk(1)` and as such, ignoring such an issue risks violating [Rule
17](rules.html#rule17) which is a big risk. Of course, using `mkiocccentry(1)`
would prevent this from happening as it would not create such a file anyway. If
`mkiocccentry(1)` was used it would rather suggest a bug in one of the tools and
you should [report it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
See [the FAQ about reporting bugs in the mkiocccentry
repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
By default, `txzchk(1)` will show the contents of the tarball which is
how the `mkiocccentry(1)` shows you the tarball contents for you to review.
</p> </p>
<p class="leftbar"> <p class="leftbar">
To help you with editing a submission, the `mkiocccentry(1)` tool has To help you with editing a submission, the `mkiocccentry(1)` tool has
some options to write _OR_ read from an answers file so you do not have to input some options to write _OR_ read from an answers file so you do not have to input
the information about the author(s) and the entry itself after saving the the information about the author(s) and the submission itself, after saving the
answers to a file. To write to `answers.txt` try: answers to a file. To write to `answers.txt` try:
</p> </p>
@@ -496,65 +466,107 @@ To make use of the answers file, use the `-i answers` option like:
mkiocccentry -i answers.txt ... mkiocccentry -i answers.txt ...
``` ```
<div id="mkiocccentry-checks">
### `mkiocccentry` checks
</div>
<p class="leftbar"> <p class="leftbar">
If you wish to manually run the commands that `mkiocccentry(1)` runs, to test `mkiocccentry(1)` will check and warn about the following conditions:
your submission, you can do so. For instance, to check the validity of the
tarball `submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz` you can
do:
</p> </p>
``` <!---sh--> - <p class="leftbar">if the files do not exist, are not regular files or cannot be read.</p>
txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz - <p class="leftbar">if `prog.c` violates [Rule 2](rules.html#rule2) (see
``` [iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if `prog.c` is empty.</p>
- <p class="leftbar">if `prog.c` has any high bit char (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if `prog.c` has any NUL char (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if `prog.c` has any unknown or invalid trigraph (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if `prog.c` triggers a word buffer overflow (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if `prog.c` triggers an `ungetc(3)` error (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).</p>
- <p class="leftbar">if the first rule in the `Makefile` is not `all`.</p>
- <p class="leftbar">if the `Makefile` does not have a `clean` rule.</p>
- <p class="leftbar">if the `Makefile` does not have a `clobber` rule.</p>
- <p class="leftbar">if the `Makefile` does not have a `try` rule.</p>
- <p class="leftbar">if the `remarks.md` is empty.</p>
<p class="leftbar"> <p class="leftbar">
Assuming that the tarball exists and is valid, you should see the Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
contents of the tarball, along with a few other minor details, and the words: it is correct, are:
</p> </p>
> No feathers stuck in tarball. - <p class="leftbar">your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.</p>
- <p class="leftbar">your _abstract_ is not between 1 and `MAX_ABSTRACT_LEN` chars
(see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">the author count is not 1 through `MAX_AUTHORS` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">an author _name_ is not 1 through `MAX_NAME_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">duplicate author _name_.</p>
- <p class="leftbar">_country code_ is invalid (not ISO 3166-1 2 character
codes).</p>
- <p class="leftbar">an _email_, if provided, is not in the format of `x@y` or
if `x` or `y` contain a `@`, are empty or if the total length is longer than
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">a _URL_ or _alt URL_, if provided, does not start with `http://`
or `https://` or is longer than `MAX_URL_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
or does not have anything after the `http://` or `https://`.</p>
- <p class="leftbar">a _mastodon handle_, if provided, is not in the form of
`@user@site` (i.e. starts with an `@`, has text following it and then another
`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">a _GitHub account_, if provided, does not start with an `@`,
has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">an _affiliation_, if provided, is longer than
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).</p>
- <p class="leftbar">an _author handle_, if the default is not accepted, does
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.</p>
- <p class="leftbar">an _author handle_ is repeated.</p>
- <p class="leftbar">the output of `ls` on the submission directory is
incorrect.</p>
<p class="leftbar"> <p class="leftbar">
If you give the option `-q` it will not report anything unless there are certain Below are the tools that `mkiocccentry(1)` will run.
error conditions; issues ('feathers' :-) ) found in the tarball are not </p>
considered errors so that one can get an overview of all the issues in the
tarball but with `-q` these will not be reported unless `-w` is used (but as <div id="iocccsize">
`-w` is meant for the test suite you do not need to concern yourself with that). ## `iocccsize`
Thus you should check the exit code if you use `-q`. </div>
<p class="leftbar">`mkiocccentry(1)` will use code from `iocccsize(1)` which
detects a number of issues that you may ignore, if you wish, as described above.
As we already discussed how to invoke this we will not include it here again.
</p>
<div id="chkentry">
## `chkentry`
</div>
<p class="leftbar">`mkiocccentry(1)` will write two JSON files: `.auth.json` and
`.info.json`. These files contain information about the author(s) and about the
submission. These files **MUST** pass the checks of `chkentry(1)`. If it does
not pass and you used `mkiocccentry(1)` it is very possibly a bug and you should
[report
it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
See the [the FAQ about reporting
bugs in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p> </p>
<p class="leftbar"> <p class="leftbar">
For instance, the following command will not show anything unless there is a Assuming that `chkentry(1)` validates both `.auth.json` and
problem with the tarball, in which case it will show `Feathers stuck in tarball `.info.json` then the tarball will be formed and then `txzchk(1)` will be
:-(`. executed. In this case, there should be no problems as `mkiocccentry(1)` should
</p> **NOT** form a tarball if there are any issues.
``` <!---sh-->
txzchk -q submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz || \
echo 'Feathers stuck in tarball :-('
```
<p class="leftbar">
Alternatively you could just check the exit code with `echo $?`; a value of 0
indicates all is OK.
</p>
<p class="leftbar">
If you wish to run `fnamchk(1)` directly you can do so like:
</p>
``` <!---sh-->
fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
```
<p class="leftbar">
Assuming everything is OK, it would show:
</p>
> `12345678-1234-4321-abcd-1234567890ab-2`
<p class="leftbar">
... which, as stated earlier, `txzchk(1)` uses.
</p> </p>
<p class="leftbar"> <p class="leftbar">
@@ -589,6 +601,97 @@ it will report this as an error**. Thus, if you were to package this manually
then you would be violating [Rule 17](rules.html#rule17). then you would be violating [Rule 17](rules.html#rule17).
</p> </p>
<div id="txzchk">
## `txzchk`
</div>
<p class="leftbar">
`txzchk(1)` performs a wide number of sanity checks on the xz
compressed tarball; if any issues are found ('`feathers are stuck in the
tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is very possibly a bug in one of the tools and you
should [report it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
`bug_report.sh` script to help us out here!** See [the FAQ about reporting bugs
in the mkiocccentry repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the
_filename_ to verify that the name is valid.
</p>
<p class="leftbar">
It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a
bug in `fnamchk(1)` and as such, ignoring such an issue risks violating [Rule
17](rules.html#rule17) which is a big risk. Of course, using `mkiocccentry(1)`
would prevent this from happening as it would not create such a file anyway. If
`mkiocccentry(1)` was used it would rather suggest a bug in one of the tools and
you should [report it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
See [the FAQ about reporting bugs in the mkiocccentry
repo](../faq.html#mkiocccentry_bugs).
</p>
<p class="leftbar">
If verbosity level is > 0, `txzchk(1)` will show the contents of the tarball which is
how the `mkiocccentry(1)` shows you the tarball contents for you to review.
</p>
<p class="leftbar">
It is beyond the scope of this document to discuss the many tests that
`txzchk(1)` do. In this case we refer you to the [source
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c) or the man
page. You might find a fun option if you do either of these!
</p>
<p class="leftbar">
If you wish to validate the tarball without running the `mkiocccentry(1)` tool,
for instance the tarball `submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz` you can
do:
</p>
``` <!---sh-->
txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
```
<p class="leftbar">
Assuming that the tarball exists and is valid, you should see no output.
</p>
<p class="leftbar">
If you wish to see the contents, for instance like `mkiocccentry(1)` does, you
could do:
</p>
``` <!---sh-->
txzchk -v 1 submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
```
<div id="fnamchk">
## `fnamchk`
</div>
<p class="leftbar">
A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of
its algorithm but if you wish to validate a submission filename you can do so:
</p>
``` <!---sh-->
fnamchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
```
<p class="leftbar">
Assuming everything is OK, it would show:
</p>
> `12345678-1234-4321-abcd-1234567890ab-2`
<p class="leftbar">
... which, as stated earlier, `txzchk(1)` uses.
</p>
<p class="leftbar"> <p class="leftbar">
At the risk of stating the obvious: you run **a very big risk** of having At the risk of stating the obvious: you run **a very big risk** of having
your submission rejected if you package your own tarball and there are **any your submission rejected if you package your own tarball and there are **any
next/rules.html
+4 -3
View File
@@ -416,7 +416,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
<h2 id="ioccc-rules-version">IOCCC Rules version</h2> <h2 id="ioccc-rules-version">IOCCC Rules version</h2>
</div> </div>
<p class="leftbar"> <p class="leftbar">
These <a href="rules.html">IOCCC rules</a> are version <strong>28.6 2024-07-10</strong>. These <a href="rules.html">IOCCC rules</a> are version <strong>28.7 2024-07-11</strong>.
</p> </p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p> <p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<div id="change_marks"> <div id="change_marks">
@@ -899,7 +899,7 @@ entry.
<p class="leftbar"> <p class="leftbar">
The <code>txzchk(1)</code> tool will verify these (and other things) for you and The <code>txzchk(1)</code> tool will verify these (and other things) for you and
the <code>chkentry(1)</code> tool will do additional checks on the contents of the the <code>chkentry(1)</code> tool will do additional checks on the contents of the
<code>.auth.json</code> and <code>.info.json</code> files including JSON validity. If these checks <code>.auth.json</code> and <code>.info.json</code> files (including JSON validity). If these checks
fail it is an error and <code>mkiocccentry(1)</code> will fail. In this case it is very fail it is an error and <code>mkiocccentry(1)</code> will fail. In this case it is very
<strong>possibly</strong> a bug; please <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues <strong>possibly</strong> a bug; please <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report it as a bug at the mkiocccentry issues
page</a>. page</a>.
@@ -908,7 +908,8 @@ page</a>.
The tarball filename <strong>MUST</strong> pass <code>fnamchk(1)</code>; the tool <code>txzchk(1)</code> The tarball filename <strong>MUST</strong> pass <code>fnamchk(1)</code>; the tool <code>txzchk(1)</code>
will run <code>fnamchk(1)</code> as part of its algorithm. If you use <code>mkiocccentry(1)</code> will run <code>fnamchk(1)</code> as part of its algorithm. If you use <code>mkiocccentry(1)</code>
there should be no problem but if you were to package things manually it is there should be no problem but if you were to package things manually it is
possible there could be a problem and this is a big risk. possible there could be a problem and this poses a big risk of violating <a href="#rule17">Rule
17</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify that the The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify that the
next/rules.md
+4 -3
View File
@@ -46,7 +46,7 @@ writing by [contacting the judges](../contact.html).
</div> </div>
<p class="leftbar"> <p class="leftbar">
These [IOCCC rules](rules.html) are version **28.6 2024-07-10**. These [IOCCC rules](rules.html) are version **28.7 2024-07-11**.
</p> </p>
**IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html). **IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
@@ -629,7 +629,7 @@ entry.</p>
<p class="leftbar"> <p class="leftbar">
The `txzchk(1)` tool will verify these (and other things) for you and The `txzchk(1)` tool will verify these (and other things) for you and
the `chkentry(1)` tool will do additional checks on the contents of the the `chkentry(1)` tool will do additional checks on the contents of the
`.auth.json` and `.info.json` files including JSON validity. If these checks `.auth.json` and `.info.json` files (including JSON validity). If these checks
fail it is an error and `mkiocccentry(1)` will fail. In this case it is very fail it is an error and `mkiocccentry(1)` will fail. In this case it is very
**possibly** a bug; please [report it as a bug at the mkiocccentry issues **possibly** a bug; please [report it as a bug at the mkiocccentry issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
@@ -639,7 +639,8 @@ page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)` The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)`
will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)` will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)`
there should be no problem but if you were to package things manually it is there should be no problem but if you were to package things manually it is
possible there could be a problem and this is a big risk. possible there could be a problem and this poses a big risk of violating [Rule
17](#rule17).
</p> </p>
<p class="leftbar"> <p class="leftbar">