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

Merge pull request #2566 from xexyl/tech-details-guidelines

Browse Source 
More details in guidelines
This commit is contained in:
Landon Curt Noll authored and GitHub committed 2024-07-11 15:56:01 -07:00
2 parents 16a28fe6ad f94c324c31
commit 03f32f4b73
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>
</div>
<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><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<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 class="leftbar">
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 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
code against <a href="rules.html#rule2">Rule 2</a>:
This IOCCC size tool imposes a 2nd limit on C code size (see <a href="rules.html#rule2a">Rule
2a</a>). To check your code against <a href="rules.html#rule2">Rule 2</a>:
</p>
<pre><code> iocccsize prog.c</code></pre>
<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>
<p class="leftbar">
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>In cases where the above summary and the algorithm implemented by
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
<a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras.
</p>
<h2 id="mkiocccentry"><code>mkiocccentry</code></h2>
<p class="leftbar">
<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.
</p>
<p class="leftbar">
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 class="leftbar">
This tool invokes a number of other tools and one, <code>txzchk(1)</code>,
invokes another, <code>fnamchk(1)</code>.
<code>mkiocccentry</code> runs a number of checks, by the tool itself and by executing other
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 class="leftbar">
Although the <code>mkiocccentry(1)</code> tool will verify everything for you,
you may wish to validate each part individually. As the <a href="rules.html">rules</a>
state, each of these tools have a <code>-h</code> option. However, to help simplify
matters, we give you a brief overview below.
If <code>mkiocccentry</code> encounters an <strong>error</strong> the program will exit and the xz
compressed tarball <strong>will not be formed</strong>. For instance, if <code>chkentry(1)</code> (see
below) 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 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:
</p>
<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
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>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
wish to submit.
</p>
@@ -680,96 +715,32 @@ the requirements of these files.
</p>
<p class="leftbar">
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
directory 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
is not a directory that can be written to. In <strong>this</strong> directory your <strong>submission
directory</strong> will be created, with the name based on your IOCCC registration
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
17</a>.
</p>
<p class="leftbar">
If the subdirectory in the work directory already exists, you will have to move
it or remove it or otherwise specify a different work directory as it needs to
be empty and the <code>mkiocccentry(1)</code> tool does not check this for you
as it could do nothing about anyway. This subdirectory is where your files will be
<strong>copied</strong> to. Your submission tarball (which you will upload to the submit
server) that <code>txzchk(1)</code> will validate will be placed in the work directory, and
its contents will be the subdirectory with your submission’s files.
If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> already exists, you will have to
move it, remove it or otherwise specify a different work directory (<strong>NOT</strong>
subdirectory), as it needs to be empty and the <code>mkiocccentry(1)</code> tool does not
check this for you as it could not do anything about anyway. This <em>subdirectory is
where your files will be <strong>copied</strong> to</em>. Your <em>submission tarball</em> (which you will
upload to the submit server) that <code>txzchk(1)</code> will validate <em>will be placed in
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 class="leftbar">
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
either <a href="rules.html#rule2a">Rule 2a</a> or <a href="rules.html#rule2b">Rule 2b</a> are broken,
it will give you the option to ignore them, if you are willing to risk this.
</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.
submission <em>as well as author details</em> (that will only be looked at if the
submission wins), run some tests and run a number of other tools, as already
mentioned and as described below.
</p>
<p class="leftbar">
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
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:
</p>
<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:
</p>
<pre><code> mkiocccentry -i answers.txt ...</code></pre>
<h3 id="mkiocccentry-checks"><code>mkiocccentry</code> checks</h3>
<p class="leftbar">
If you wish to manually run the commands that <code>mkiocccentry(1)</code> runs, to test
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:
<code>mkiocccentry(1)</code> will check and warn about the following conditions:
</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">
Assuming that the tarball exists and is valid, you should see the
contents of the tarball, along with a few other minor details, and the words:
Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
it is correct, are:
</p>
<blockquote>
<p>No feathers stuck in tarball.</p>
</blockquote>
<ul>
<li><p class="leftbar">
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">
If you give the option <code>-q</code> it will not report anything unless there are certain
error conditions; issues (‘feathers’ :-) ) found in the tarball are not
considered errors so that one can get an overview of all the issues in the
tarball but with <code>-q</code> these will not be reported unless <code>-w</code> is used (but as
<code>-w</code> is meant for the test suite you do not need to concern yourself with that).
Thus you should check the exit code if you use <code>-q</code>.
Below are the tools that <code>mkiocccentry(1)</code> will run.
</p>
<h2 id="iocccsize"><code>iocccsize</code></h2>
<p class="leftbar">
<code>mkiocccentry(1)</code> will use code from <code>iocccsize(1)</code> 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>
<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 class="leftbar">
For instance, the following command will not show anything unless there is a
problem with the tarball, in which case it will show <code>Feathers stuck in tarball :-(</code>.
</p>
<pre><code> txzchk -q submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz || \
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.
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.
</p>
<p class="leftbar">
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
then you would be violating <a href="rules.html#rule17">Rule 17</a>.
</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">
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
next/guidelines.md
+252 -149
View File
@@ -46,7 +46,7 @@ writing by [contacting the judges](../contact.html).
</div>
<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>
**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">
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 class="leftbar">
This IOCCC size tool imposes a 2nd limit on C code size (see [Rule 2a](rules.html#rule2a). To check your
code against [Rule 2](rules.html#rule2):
This IOCCC size tool imposes a 2nd limit on C code size (see [Rule
2a](rules.html#rule2a)). To check your code against [Rule 2](rules.html#rule2):
</p>
``` <!---sh-->
@@ -298,7 +298,7 @@ ASCII formfeed, and ASCII carriage return.
<p class="leftbar">
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
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.
</p>
<div id="mkiocccentry">
## `mkiocccentry`
</div>
<p class="leftbar">
[Rule 17](rules.html#rule17) (the `mkiocccentry(1)` rule) states that
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">
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 class="leftbar">
This tool invokes a number of other tools and one, `txzchk(1)`,
invokes another, `fnamchk(1)`.
`mkiocccentry` runs a number of checks, by the tool itself and by executing other
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 class="leftbar">
Although the `mkiocccentry(1)` tool will verify everything for you,
you may wish to validate each part individually. As the [rules](rules.html)
state, each of these tools have a `-h` option. However, to help simplify
matters, we give you a brief overview below.
If `mkiocccentry` encounters an **error** the program will exit and the xz
compressed tarball **will not be formed**. For instance, if `chkentry(1)` (see
below) 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 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">
The synopsis of the `mkiocccentry(1)` tool is:
</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
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
`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
wish to submit.
</p>
@@ -372,109 +416,35 @@ the requirements of these files.
<p class="leftbar">
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
directory will be created, with the name based on your IOCCC registration
username **in the form of a UUID** and submission number; see the
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
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
17](rules.html#rule17).
</p>
<p class="leftbar">
If the subdirectory in the work directory already exists, you will have to move
it or remove it or otherwise specify a different work directory as it needs to
be empty and the `mkiocccentry(1)` tool does not check this for you
as it could do nothing about anyway. This subdirectory is where your files will be
**copied** to. Your submission tarball (which you will upload to the submit
server) that `txzchk(1)` will validate will be placed in the work directory, and
its contents will be the subdirectory with your submission's files.
If the **_subdirectory_ in the _work directory_** already exists, you will have to
move it, remove it or otherwise specify a different work directory (**NOT**
subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not
check this for you as it could not do anything about anyway. This _subdirectory is
where your files will be **copied** to_. Your _submission tarball_ (which you will
upload to the submit server) that `txzchk(1)` will validate _will be placed in
the **work directory**_, and **its _contents_ will be the _subdirectory_ with your
submission's files**.
</p>
<p class="leftbar">
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
either [Rule 2a](rules.html#rule2a) or [Rule 2b](rules.html#rule2b) are broken,
it will give you the option to ignore them, if you are willing to risk this.
</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.
submission _as well as author details_ (that will only be looked at if the
submission wins), run some tests and run a number of other tools, as already
mentioned and as described below.
</p>
<p class="leftbar">
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
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:
</p>
@@ -496,65 +466,107 @@ To make use of the answers file, use the `-i answers` option like:
mkiocccentry -i answers.txt ...
```
<div id="mkiocccentry-checks">
### `mkiocccentry` checks
</div>
<p class="leftbar">
If you wish to manually run the commands that `mkiocccentry(1)` runs, to test
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:
`mkiocccentry(1)` will check and warn about the following conditions:
</p>
``` <!---sh-->
txzchk submit.12345678-1234-4321-abcd-1234567890ab-2.1720636351.txz
```
- <p class="leftbar">if the files do not exist, are not regular files or cannot be read.</p>
- <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">
Assuming that the tarball exists and is valid, you should see the
contents of the tarball, along with a few other minor details, and the words:
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
it is correct, are:
</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">
If you give the option `-q` it will not report anything unless there are certain
error conditions; issues ('feathers' :-) ) found in the tarball are not
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
`-w` is meant for the test suite you do not need to concern yourself with that).
Thus you should check the exit code if you use `-q`.
Below are the tools that `mkiocccentry(1)` will run.
</p>
<div id="iocccsize">
## `iocccsize`
</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 class="leftbar">
For instance, the following command will not show anything unless there is a
problem with the tarball, in which case it will show `Feathers stuck in tarball
:-(`.
</p>
``` <!---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.
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.
</p>
<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).
</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">
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
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>
</div>
<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><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<div id="change_marks">
@@ -899,7 +899,7 @@ entry.
<p class="leftbar">
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
<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
<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>.
@@ -908,7 +908,8 @@ page</a>.
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>
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 class="leftbar">
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>
<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>
**IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
@@ -629,7 +629,7 @@ entry.</p>
<p class="leftbar">
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
`.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
**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).
@@ -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)`
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
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 class="leftbar">