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

Various updates/fixes for recent chkentry mods

Browse Source
This commit is contained in:
Cody Boone Ferguson committed 2025-02-26 12:20:55 -08:00
1 parent 7e559b6da1
commit 664a7b57bd
8 files changed
+804 -601
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

next/guidelines.html
+68 -36
View File
@@ -436,8 +436,9 @@ Mastodon</a> feed as <em>sometimes</em> the
<p>See our
FAQ on “<a href="../faq.html#feedback">rules, guidelines, tools feedback</a>”
as well as our
FAQ on “<a href="../faq.html#question">about asking questions</a>”
about these guidelines. You might also find the FAQ in general useful, especially the
FAQ on “<a href="../faq.html#question">asking questions</a>”
about these rules. You might also find the FAQ in general useful, as well as the
<a href="../quick-start.html">quick start guide</a> and <a href="register.html">how to register</a>.
FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”.</p>
<h1 id="the-ioccc-is-pending">The IOCCC is pending</h1>
<p>While the IOCCC is not open yet, there is a tentative opening date for the next IOCCC.</p>
@@ -461,11 +462,11 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
</div>
</div>
<p class="leftbar">
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.38 2025-02-12</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.39 2025-02-26</strong>.
</p>
<p class="leftbar">
The <a href="guidelines.md" download="guidelines.md">markdown form of these guidelines</a>
is available for download.
The markdown form of these guidelines <a href="guidelines.md"
download="guidelines.md">is available for download</a>.
</p>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<p>Jump to: <a href="#">top</a></p>
@@ -602,11 +603,12 @@ The <code>-d</code> option is an alias for <code>-s 21701</code>. An example use
</p>
<pre><code> mkiocccentry -d workdir topdir</code></pre>
<p class="leftbar">
where <code>workdir</code> is the directory which the tarball will be formed and the
where <code>workdir</code> is the directory where the tarball will be formed and the
<code>topdir</code> is the directory which has the required files (<code>prog.c</code>, <code>Makefile</code> and
<code>remarks.md</code>) along with extra data files you wish to submit. Be aware
that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in normal mode.
<code>remarks.md</code>) along with extra data files (and if you wish, directories) you
wish to submit. Be aware that if the directory exists already, you will have to
remove it or move it before this option will work a second time, just like in
normal mode.
</p>
<p class="leftbar">
<strong>IMPORTANT NOTE</strong>: if you run the program outside the repo directory
@@ -616,9 +618,10 @@ are required like <code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fna
have installed them but some tools are out of date (in the install path) it will
cause problems. Additionally, if you do not have the most recent version when
submitting a tarball it will be rejected for not having the right versions of
the tools. This is why you <strong>MUST</strong> make sure you have the most recent
version of all the tools and you either run it from the repo directory itself OR
you install them (<code>make install</code> as root or via <code>sudo</code>).
the tools. This is why you <strong>MUST</strong> make sure you have the most recent version
of all the tools and you either run it from the repo directory itself OR you
install them (<code>make install</code> as via <code>sudo</code> or as root). We recommend you install
the tools but if you wish to run it from the repo directory you may.
</p>
<p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> has been <strong>significantly modified</strong>
@@ -652,8 +655,8 @@ previously uploaded submission by rebuilding your submission with the
To help you with this, so that you do not have to repeatedly answer all the
questions, the <code>mkiocccentry(1)</code> tool has the options <code>-a answers</code>, <code>-A answers</code>
and <code>-i answers</code>, where <code>-a</code> will write to an answers file (if it does not
already exist), <code>-A</code> will overwrite the file and <code>-i</code> will read the answers from
the file. If you use <code>-A</code>, be sure you don’t overwrite another file by accident!
already exist), <code>-A</code> <strong>WILL OVERWRITE THE FILE</strong> and <code>-i</code> will read the answers from
the file. If you use <code>-A</code>, <strong>BE SURE</strong> you don’t overwrite another file by accident!
</p>
<p class="leftbar">
Once the contest enters the <strong><a href="../status.html#judging">judging</a></strong> state, you will
@@ -854,10 +857,11 @@ its algorithm.
</p>
<p class="leftbar">
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 (see below) that <code>mkiocccentry(1)</code> creates,
it is an error and <strong>possibly</strong> 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
compressed tarball <strong>will not be formed</strong>. For instance, if
<a href="#chkentry">chkentry(1)</a> 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 (see below) that
<code>mkiocccentry(1)</code> creates, or anything else <code>mkiocccentry(1)</code> does, it is an
<strong>error</strong> and <strong>possibly</strong> 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 bug report
page</a>.
<strong>PLEASE run the <code>bug_report.sh</code> script to help us out here!</strong> See the
@@ -878,7 +882,9 @@ Needless to say, we do <strong>NOT</strong> 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.
correct details as you go along. Be advised that there is a default answer and
if you press enter it will proceed with that default, so make sure you have
provided the correct answer.
</p>
<p>Jump to: <a href="#">top</a></p>
<div id="mkiocccentry-synopsis">
@@ -891,9 +897,10 @@ The synopsis of the <code>mkiocccentry(1)</code> tool is:
<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 submission more than once (unless of
the information about the author(s) and the submission more than once, unless of
course you need to make some changes, in which case you can use the option that
overwrites the file).
overwrites the file. If you do use the overwrite option, <strong>MAKE SURE</strong> you do
not overwrite another file!
</p>
<p class="leftbar">
See the
@@ -911,8 +918,9 @@ execute one or more additional tools.
</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 noted above.
<code>mkiocccentry(1)</code> will use code from <code>iocccsize(1)</code> which detects a number of
issues (such as <a href="rules.html#rule2">Rule 2</a>) that you may ignore, if you wish, as
noted above.
</p>
<p class="leftbar">
In other words, you no longer need to run <code>iocccsize</code> manually. However, the
@@ -929,7 +937,12 @@ submission. These files <strong>MUST</strong> pass the checks of <code>chkentry(
If <code>chkentry</code> does not pass and you used <code>mkiocccentry(1)</code> it is <strong>very likely</strong> 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
<strong>PLEASE</strong> run the command:
</p>
<pre><code> make bug_report</code></pre>
<p class="leftbar">
from the top level repo directory itself.
See also the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
@@ -939,10 +952,15 @@ executed on it. In this case, there should be no problems, as <code>mkiocccentry
<strong>NOT</strong> form a tarball if there are any issues.
</p>
<p class="leftbar">
If <code>mkiocccentry(1)</code> is used and <code>chkentry(1)</code> fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
<strong>NOTE</strong>: <code>chkentry(1)</code> also validates other things in your submission
directory.
</p>
<p class="leftbar">
If <code>mkiocccentry(1)</code> is used and <code>chkentry(1)</code> fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, though this is quite
unlikely.
unlikely. Nonetheless, if you believe there is a bug, you may report it as
explained above.
</p>
<p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the
@@ -993,15 +1011,16 @@ installed separately, in order to use the tools in <code>mkiocccentry</code>.
In other words, <code>mkiocccentry</code> <strong>contains everything</strong> you need, and <em>even if you
do install</em> the libraries from their respective repos, it/they will <strong>not be
used</strong> when compiling the <code>mkiocccentry</code> tools. This is important to
make sure that you’re using the correct versions, which is verified by
<code>chkentry</code>. See <a href="rules.html#rule17">Rule 17</a>!
make sure that you’re using the correct versions, which is also verified by
<code>chkentry</code> (in the JSON files created by <code>mkiocccentry(1)</code>). See <a href="rules.html#rule17">Rule
17</a>!
</p>
<p class="leftbar">
Please see the
FAQ on “<a href="../faq.html#chkentry">validating .auth.json and/or .info.json files</a>
for more details on <code>chkentry</code> and how you can use it to validate your
<code>.auth.json</code> and <code>.info.json</code> files manually, without having to repackage your
submission.
<code>.auth.json</code> and <code>.info.json</code> files (and your submission directory in general)
manually, without having to repackage your submission.
</p>
<p class="leftbar">
You might also wish to see the
@@ -1018,7 +1037,8 @@ compressed tarball; if any issues are found (‘<code>feathers are stuck in the
<code>mkiocccentry(1)</code></strong>, then it is <strong>possibly</strong> a bug in one of the tools and you
might want to <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 bug report
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See the
<code>bug_report.sh</code> script to help us out here!</strong> You may do this by running from
the top level directory of the repo <code>make bug_report</code>. See the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
@@ -1055,9 +1075,9 @@ an extra file, not an optional file.
<p class="leftbar">
In particular, any file that is not <code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code>,
<code>try.sh</code>, <code>prog.alt.c</code> or <code>try.alt.sh</code> will be counted as an extra file, and if
<code>try.sh</code>, <code>prog.alt.c</code> or <code>try.alt.sh</code> are not in the top level directory they
will also be counted as an extra file. The <code>.info.json</code> and <code>.auth.json</code> files
are not counted as extra files but are required.
<code>try.sh</code>, <code>prog.alt.c</code> or <code>try.alt.sh</code> are not in the top level submission
directory they will also be counted as an extra file. The <code>.info.json</code> and
<code>.auth.json</code> files are not counted as extra files but are required.
</p>
<p class="leftbar">
In other words, the actual amount of <strong>EXTRA</strong> files is 31.
@@ -1078,7 +1098,9 @@ section</a> for more details on this important tool.
</p>
<p class="leftbar">
If you <strong>DO</strong> include a tarball, and the build process or the program extracts
said tarball(s), the make <code>clobber</code> rule <strong>MUST</strong> remove them.
said tarball(s), the make <code>clobber</code> rule <strong>MUST</strong> remove them. Even so, if you
include a tarball to get past the limit on the number of files, you <strong>MUST</strong>
justify this in your remarks!
</p>
<p class="leftbar">
<strong>IMPORTANT REMINDER</strong>: make <strong>SURE</strong> your tarball does <strong>NOT</strong> reveal who you are!
@@ -1442,6 +1464,10 @@ use of <code>git(1)</code> or <code>gh(1)</code>, just be sure that your submiss
submission Makefile don’t depend on such tools.
</p>
<p class="leftbar">
Of course if you do use GitHub to work on your submission, you might want to
make the repo private so you don’t reveal who you are. :-)
</p>
<p class="leftbar">
If this is not clear, please do <strong>NOT</strong> use these tools to help with the
<code>clobber</code> rule! For instance, do <strong>NOT</strong> use <code>git clean</code>! Not only does this
depend on the user having <code>git(1)</code> but it also does not account for the
@@ -1461,6 +1487,12 @@ In other words, for <code>make clobber</code>, do something like:
<p class="leftbar">
And do <strong>NOT</strong> use <code>git</code> for any other tool either.
</p>
<p class="leftbar">
<strong>NOTE</strong>: <code>mkiocccentry(1)</code> will directly run <code>make clobber</code> in the submission
directory. An although it is not an error if this fails, if it fails because the
Makefile does not have a clobber rule, it will be flagged by <code>mkiocccentry(1)</code>
(you may ignore this but it does put you at a risk of violating the rules).
</p>
<p>Jump to: <a href="#">top</a></p>
<div id="likes">
<div id="dislikes">
next/guidelines.md
+75 -38
View File
@@ -14,8 +14,9 @@ Mastodon](https://fosstodon.org/@ioccc) feed as _sometimes_ the
See our
FAQ on "[rules, guidelines, tools feedback](../faq.html#feedback)"
as well as our
FAQ on "[about asking questions](../faq.html#question)"
about these guidelines. You might also find the FAQ in general useful, especially the
FAQ on "[asking questions](../faq.html#question)"
about these rules. You might also find the FAQ in general useful, as well as the
[quick start guide](../quick-start.html) and [how to register](register.html).
FAQ on "[how to enter the IOCCC](../quick-start.html#enter)".
@@ -49,12 +50,12 @@ Jump to: [top](#)
</div>
<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.38 2025-02-12**.
These [IOCCC guidelines](guidelines.html) are version **28.39 2025-02-26**.
</p>
<p class="leftbar">
The <a href="guidelines.md" download="guidelines.md">markdown form of these guidelines</a>
is available for download.
The markdown form of these guidelines <a href="guidelines.md"
download="guidelines.md">is available for download</a>.
</p>
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -226,11 +227,12 @@ The `-d` option is an alias for `-s 21701`. An example use:
```
<p class="leftbar">
where `workdir` is the directory which the tarball will be formed and the
where `workdir` is the directory where the tarball will be formed and the
`topdir` is the directory which has the required files (`prog.c`, `Makefile` and
`remarks.md`) along with extra data files you wish to submit. Be aware
that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in normal mode.
`remarks.md`) along with extra data files (and if you wish, directories) you
wish to submit. Be aware that if the directory exists already, you will have to
remove it or move it before this option will work a second time, just like in
normal mode.
</p>
<p class="leftbar">
@@ -241,9 +243,10 @@ are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
have installed them but some tools are out of date (in the install path) it will
cause problems. Additionally, if you do not have the most recent version when
submitting a tarball it will be rejected for not having the right versions of
the tools. This is why you **MUST** make sure you have the most recent
version of all the tools and you either run it from the repo directory itself OR
you install them (`make install` as root or via `sudo`).
the tools. This is why you **MUST** make sure you have the most recent version
of all the tools and you either run it from the repo directory itself OR you
install them (`make install` as via `sudo` or as root). We recommend you install
the tools but if you wish to run it from the repo directory you may.
</p>
<p class="leftbar">
@@ -283,8 +286,8 @@ previously uploaded submission by rebuilding your submission with the
To help you with this, so that you do not have to repeatedly answer all the
questions, the `mkiocccentry(1)` tool has the options `-a answers`, `-A answers`
and `-i answers`, where `-a` will write to an answers file (if it does not
already exist), `-A` will overwrite the file and `-i` will read the answers from
the file. If you use `-A`, be sure you don't overwrite another file by accident!
already exist), `-A` **WILL OVERWRITE THE FILE** and `-i` will read the answers from
the file. If you use `-A`, **BE SURE** you don't overwrite another file by accident!
</p>
<p class="leftbar">
@@ -531,10 +534,11 @@ its algorithm.
<p class="leftbar">
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 (see below) that `mkiocccentry(1)` creates,
it is an error and **possibly** a bug that you should [report as a bug at the
compressed tarball **will not be formed**. For instance, if
[chkentry(1)](#chkentry) fails to validate the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files (see below) that
`mkiocccentry(1)` creates, or anything else `mkiocccentry(1)` does, it is an
**error** and **possibly** a bug that you should [report as a bug at the
mkiocccentry bug report
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
@@ -558,7 +562,9 @@ Needless to say, we do **NOT** recommend these options.
<p class="leftbar">
In many places it will prompt you to verify what you input, allowing you to
correct details as you go along.
correct details as you go along. Be advised that there is a default answer and
if you press enter it will proceed with that default, so make sure you have
provided the correct answer.
</p>
@@ -579,9 +585,10 @@ The synopsis of the `mkiocccentry(1)` tool is:
<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 submission more than once (unless of
the information about the author(s) and the submission more than once, unless of
course you need to make some changes, in which case you can use the option that
overwrites the file).
overwrites the file. If you do use the overwrite option, **MAKE SURE** you do
not overwrite another file!
</p>
<p class="leftbar">
@@ -607,8 +614,9 @@ execute one or more additional tools.
</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 noted above.
`mkiocccentry(1)` will use code from `iocccsize(1)` which detects a number of
issues (such as [Rule 2](rules.html#rule2)) that you may ignore, if you wish, as
noted above.
</p>
<p class="leftbar">
@@ -631,7 +639,16 @@ submission. These files **MUST** pass the checks of `chkentry(1)`!
If `chkentry` does not pass and you used `mkiocccentry(1)` it is **very likely** 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
**PLEASE** run the command:
</p>
``` <!---sh-->
make bug_report
```
<p class="leftbar">
from the top level repo directory itself.
See also the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
@@ -643,10 +660,16 @@ executed on it. In this case, there should be no problems, as `mkiocccentry(1)`
</p>
<p class="leftbar">
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
**NOTE**: `chkentry(1)` also validates other things in your submission
directory.
</p>
<p class="leftbar">
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though this is quite
unlikely.
unlikely. Nonetheless, if you believe there is a bug, you may report it as
explained above.
</p>
<p class="leftbar">
@@ -703,16 +726,17 @@ installed separately, in order to use the tools in `mkiocccentry`.
In other words, `mkiocccentry` **contains everything** you need, and _even if you
do install_ the libraries from their respective repos, it/they will **not be
used** when compiling the `mkiocccentry` tools. This is important to
make sure that you're using the correct versions, which is verified by
`chkentry`. See [Rule 17](rules.html#rule17)!
make sure that you're using the correct versions, which is also verified by
`chkentry` (in the JSON files created by `mkiocccentry(1)`). See [Rule
17](rules.html#rule17)!
</p>
<p class="leftbar">
Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
for more details on `chkentry` and how you can use it to validate your
`.auth.json` and `.info.json` files manually, without having to repackage your
submission.
`.auth.json` and `.info.json` files (and your submission directory in general)
manually, without having to repackage your submission.
</p>
<p class="leftbar">
@@ -736,7 +760,8 @@ tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is **possibly** a bug in one of the tools and you
might want to [report it as a bug at the mkiocccentry bug report
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
`bug_report.sh` script to help us out here!** You may do this by running from
the top level directory of the repo `make bug_report`. See the
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
@@ -780,9 +805,9 @@ an extra file, not an optional file.
<p class="leftbar">
In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
will also be counted as an extra file. The `.info.json` and `.auth.json` files
are not counted as extra files but are required.
`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level submission
directory they will also be counted as an extra file. The `.info.json` and
`.auth.json` files are not counted as extra files but are required.
</p>
<p class="leftbar">
@@ -807,7 +832,9 @@ section](#txzchk) for more details on this important tool.
<p class="leftbar">
If you **DO** include a tarball, and the build process or the program extracts
said tarball(s), the make `clobber` rule **MUST** remove them.
said tarball(s), the make `clobber` rule **MUST** remove them. Even so, if you
include a tarball to get past the limit on the number of files, you **MUST**
justify this in your remarks!
</p>
<p class="leftbar">
@@ -835,8 +862,6 @@ in your `remarks.md`).
</p>
<p class="leftbar">
See also the
FAQ on "[txzchk](../faq.html#txzchk)".
@@ -1282,6 +1307,11 @@ use of `git(1)` or `gh(1)`, just be sure that your submission code and your
submission Makefile don't depend on such tools.
</p>
<p class="leftbar">
Of course if you do use GitHub to work on your submission, you might want to
make the repo private so you don't reveal who you are. :-)
</p>
<p class="leftbar">
If this is not clear, please do **NOT** use these tools to help with the
`clobber` rule! For instance, do **NOT** use `git clean`! Not only does this
@@ -1314,6 +1344,13 @@ And do **NOT** use `git` for any other tool either.
</p>
<p class="leftbar">
**NOTE**: `mkiocccentry(1)` will directly run `make clobber` in the submission
directory. An although it is not an error if this fails, if it fails because the
Makefile does not have a clobber rule, it will be flagged by `mkiocccentry(1)`
(you may ignore this but it does put you at a risk of violating the rules).
</p>
Jump to: [top](#)
<div id="likes">
next/rules.html
+86 -62
View File
@@ -437,8 +437,8 @@ Mastodon</a> feed as <em>sometimes</em> the
FAQ on “<a href="../faq.html#feedback">rules, guidelines, tools feedback</a>”
as well as our
FAQ on “<a href="../faq.html#question">about asking questions</a>”
about these rules. You might also find the FAQ in general useful, especially the
FAQ on “<a href="../quick-start.html#enter">how to enter the IOCCC</a>”.</p>
about these rules. You might also find the FAQ in general useful, as well as the
<a href="../quick-start.html">quick start guide</a> and <a href="register.html">how to register</a>.</p>
<h1 id="the-ioccc-is-pending">The IOCCC is pending</h1>
<p>While the IOCCC is not open now, there is a tentative opening date for the next IOCCC.</p>
<p>Comments and suggestions on these preliminary rules are welcome. See the
@@ -461,11 +461,11 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
</div>
</div>
<p class="leftbar">
These <a href="rules.html">IOCCC rules</a> are version <strong>28.24 2025-02-12</strong>.
These <a href="rules.html">IOCCC rules</a> are version <strong>28.25 2025-02-26</strong>.
</p>
<p class="leftbar">
The <a href="rules.md" download="rules.md">markdown form of these rules</a>
is available for download.
The markdown form of these rules <a href="rules.md" download="rules.md">is
available for download</a>.
</p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<p>Jump to: <a href="#">top</a></p>
@@ -859,7 +859,7 @@ super-user, special owner, special group, etc.) are still <strong>HIGHLY
DISCOURAGED</strong>. We do not guarantee these functions will behave as
you expect on our test platforms. If your program needs special
permissions you <strong>MUST</strong> document this fact, and explain why
it is needed in your submissions <code>remarks.md</code> file.</p>
it is needed in your submission’s <code>remarks.md</code> file.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="rule12">
<h2 id="rule-12">Rule 12</h2>
@@ -978,10 +978,9 @@ and <code>.auth.json</code>) and files that are also not the optional files (<co
<p>Jump to: <a href="#">top</a></p>
<h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
<p class="leftbar">
Each submission <strong>MUST</strong> be in the form of a xz compressed tarball.
<p>Each submission <strong>MUST</strong> be in the form of a xz compressed tarball.
The xz compressed tarball filename must be of the form:
</p>
<pre><code> ^submit.username-slot_num.[1-9][0-9]{9,}.txz$</code></pre>
<code>^submit.username-slot_num.[1-9][0-9]{9,}.txz$</code>.</p>
<p class="leftbar">
… where <em><code>username</code></em> is your IOCCC registration username <strong>in the form of a
<a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a></strong> (see
@@ -993,7 +992,7 @@ details), and where <em><code>slot_num</code></em> is a single decimal digit int
In particular, <code>username</code> is in the form of:
<code>xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx</code> where <code>'x'</code> is a hex digit in the range
of <code>[0-9a-f]</code>, 4 is the UUID version, and <code>N</code> is one of <code>8</code>, <code>9</code>, <code>a</code>, or <code>b</code>.
And yes, there is a 4 (UUID version 4) and variants <code>0x8</code>, <code>0x9</code>, <code>0xa</code> and
And yes, there is a 4 (UUID version 4) and the variants <code>0x8</code>, <code>0x9</code>, <code>0xa</code> and
<code>0xb</code> in there.
</p>
<p class="leftbar">
@@ -1001,40 +1000,27 @@ Your xz compressed tarball <strong>MUST</strong> contain, <strong>at a minimum</
</p>
<ul>
<li><p class="leftbar">
<code>Makefile</code>
<code>prog.c</code>
</p></li>
<li><p class="leftbar">
<code>prog.c</code>
<code>Makefile</code>
</p></li>
<li><p class="leftbar">
<code>remarks.md</code>
</p></li>
<li><p class="leftbar">
<code>.info.json</code>
<code>.auth.json</code>
</p></li>
<li><p class="leftbar">
<code>.auth.json</code>
<code>.info.json</code>
</p></li>
</ul>
<p class="leftbar">
The <code>.info.json</code> is generated by the <code>mkiocccentry(1)</code> tool. If not, and it is
not valid JSON or it does not pass the <code>chkentry(1)</code> tool, your submission
<strong>WILL BE</strong> rejected! If you do use <code>mkiocccentry(1)</code> and it fails to pass
<code>chkentry(1)</code> then you might wish to <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>.
</p>
<p class="leftbar">
The <code>.auth.json</code> is generated by the <code>mkiocccentry(1)</code> tool. If not, and it is
not valid JSON or it does not pass the <code>chkentry(1)</code> tool, your submission
<strong>WILL BE</strong> rejected! If you do use <code>mkiocccentry(1)</code> and it fails to pass
<code>chkentry(1)</code> then you might wish to <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>.
<code>prog.c</code> is of course your submission program.
</p>
<p class="leftbar">
The <code>Makefile</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in <strong><a href="https://www.gnu.org/software/make/manual/make.html">GNU
Makefile</a></strong> form. See the
Makefile</a></strong> format. See the
<a href="guidelines.html#makefile">Makefile section in the guidelines</a>,
the
FAQ on “<a href="../faq.html#submission_makefiles">submission Makefile</a>”
@@ -1043,7 +1029,7 @@ FAQ on “<a href="../faq.html#make_compatibility">Makefile compatibility</a>”
for help.
</p>
<p class="leftbar">
The <code>remarks.md</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in markdown form
The <code>remarks.md</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in markdown format
(<code>mkiocccentry(1)</code> only checks the file size but if you do not have any text in
it you still risk violating this rule). See also
<a href="#rule18">Rule 18</a> and our
@@ -1057,13 +1043,40 @@ See also the <a href="https://www.markdownguide.org/basic-syntax">markdown synta
and the <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.
</p>
<p class="leftbar">
The xz compressed tarball file <strong>MUST</strong> be less than or equal to <strong>3999971</strong> octets in size.
The <code>.auth.json</code> file is created by <code>mkiocccentry(1)</code> and it holds information
about the author(s) of the submission. It will <strong>ONLY</strong> be looked at if your
submission wins but it <strong>MUST</strong> still be valid according to <code>chkentry(1)</code>.
</p>
<p class="leftbar">
The <code>.info.json</code> file is created by <code>mkiocccentry(1)</code> and it holds information
about the submission itself. It also <strong>MUST</strong> be valid according to
<code>chkentry(1)</code>.
</p>
<p class="leftbar">
For the complete <code>mkiocccentry(1)</code> process, see the
FAQ on the “<a href="../faq.html#mkiocccentry_process">mkiocccentry process</a>.
</p>
<p class="leftbar">
The tool performs a lot of checks, both directly and indirectly, and if it or
any other tool detects <strong>ANY</strong> problem, you are <strong>HIGHLY</strong> encouraged to fix it
and try again.
</p>
<p class="leftbar">
If you do use <code>mkiocccentry(1)</code> and you run into a problem, you might see the
FAQ on “<a href="../faq.html#questions">how to ask a question about the IOCCC rules, guidelines and
tools</a>”.
If you believe you have encountered a bug, feel free to open a bug report at the
<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">mkiocccentry repo issues
page</a>.
</p>
<p class="leftbar">
The xz compressed tarball file <strong>MUST</strong> be &lt;= <strong>3999971</strong> octets in size.
</p>
<p class="leftbar">
When your submission’s xz compressed tarball is uncompressed,
the total size of your submission: the sum of the size of the program,
hints, comments, build and info files <strong>MUST</strong> be less than or equal
to <strong>28314624</strong> octets (<strong>27651K</strong>) in size.
the total size of your submission (the sum of the size of the program,
hints, comments, build and info files) <strong>MUST</strong> be &lt;=
<strong>28314624</strong> octets (<strong>27651K</strong>) in size.
</p>
<p class="leftbar">
Your submission’s xz compressed tarball <strong>MUST</strong> pass the <code>txzchk(1)</code> test. See
@@ -1101,7 +1114,7 @@ Be &lt;= <strong>38</strong> characters in length.
<li><p class="leftbar">
<strong>NOT</strong> contain a path component of: <strong><code>.</code></strong> (that is, with
the exception of files generated by <code>mkiocccentry(1)</code> itself, it must have
<strong>NO</strong> <strong><code>.</code></strong>).
<strong>NO</strong> <strong><code>.</code></strong> an <strong>NO</strong> dot file).
</p></li>
<li><p class="leftbar">
<strong>NOT</strong> contain a path component of: <strong><code>..</code></strong> (that is,
@@ -1134,8 +1147,8 @@ entry.
</p></li>
</ul>
<p class="leftbar">
The <code>chkentry(1)</code> tool will validate these two JSON files <em>prior to</em> the tarball
being formed.
The <code>chkentry(1)</code> tool will validate these two JSON files, and do other checks
on your submission directory as well, <em>prior to</em> forming the tarball.
</p>
<p class="leftbar">
Files and directories in your submission tarball <strong>MUST</strong> be specific
@@ -1144,17 +1157,22 @@ permissions and <code>mkiocccentry(1)</code> does this for you. In particular: d
<code>try.alt.sh</code>, if provided, <strong>MUST</strong> be <code>-r-xr-xr-x</code> (i.e. <code>0555</code>) and all other
files <strong>MUST</strong> be <code>-r--r--r--</code> (i.e. <code>0444</code>). If the files do not have these
permissions, your submission <strong>WILL</strong> be rejected for violating <a href="#rule17">Rule
17</a>! If you do need different permissions, then see the
17</a>! In addition to <code>mkiocccentry(1)</code> creating and copying the
directories and files with these modes, it also verifies them after the fact and
if they are not correct it is an <strong>error</strong>.
</p>
<p class="leftbar">
If you do need different permissions, then see the
FAQ on “<a href="../faq.html#file_perms">file permissions</a>”. Also keep in mind
<a href="#rule4">Rule 4</a>, <a href="#rule5">Rule 5</a> and <a href="#rule21">Rule 21</a>.
</p>
<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
fail it is an error and <code>mkiocccentry(1)</code> will fail. In this case (it fails and
you used <code>mkiocccentry(1)</code>) 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
The <code>txzchk(1)</code> tool will also verify file/directory permissions (and many other
things) for you and so will <code>chkentry(1)</code> (along with validating the JSON files
and running semantics checks on them). If these checks fail it is an <strong>error</strong>
and <code>mkiocccentry(1)</code> will fail. In this case (it fails and you used
<code>mkiocccentry(1)</code>) 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>.
</p>
<p class="leftbar">
@@ -1166,7 +1184,9 @@ possible there could be a problem and this poses a big risk of violating <a href
</p>
<p class="leftbar">
The <code>fnamchk(1)</code>, which <code>txzchk(1)</code> executes, will verify that the
filename is correct.
filename is correct. But if you do package your tarball manually, and you have a
mismatch in what is in the tarball and the name, <code>txzchk(1)</code> will flag the
discrepancy as an error and exit with non-zero.
</p>
<p class="leftbar">
These checks <strong>MUST PASS</strong>. If they do not you stand a significant chance of
@@ -1179,7 +1199,7 @@ having your submission rejected for violating <a href="#rule17">Rule 17</a>!
The maximum number of files your submission tarball may contain, not counting
the optional files (<code>prog.alt.c</code>, <code>try.sh</code>, <code>try.alt.sh</code>) and the mandatory
files (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code> plus the <code>mkiocccentry(1)</code> generated
files <code>.auth.json</code> and <code>.info.json</code>) is 31. This is defined in the macro
files <code>.auth.json</code> and <code>.info.json</code>), is 31. This is defined in the macro
<code>MAX_EXTRA_FILE_COUNT</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">soup/limit_ioccc.h</a>
in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>. See the
@@ -1191,7 +1211,8 @@ If you do include a tarball that takes your extra files count over the maximum,
you <strong>MUST</strong> explain this in your <code>remarks.md</code> file! <strong>PLEASE</strong> do not include a
tarball with extra files for a test-suite; instead mention in your remarks that
you have extra files for a test-suite that can be included should your
submission win.
submission win. Of course if you don’t need that many files for a test-suite you
are more than welcome to include those files in your submission.
</p>
<p class="leftbar">
If you need to extract a tarball by some Makefile, or perhaps the program
@@ -1199,13 +1220,14 @@ itself, then <code>make clobber</code> <strong>MUST</strong> remove everything t
created!
</p>
<p class="leftbar">
Tarballs <strong>MUST</strong> only create files and directories <em>under them</em>. They may
<strong>NOT</strong> contain absolute paths (paths that start with <code>/</code>)! <code>txzchk</code> only checks
the submission tarball so you must verify these details yourself.
Tarballs <strong>MUST</strong> only create files and directories <em>under</em> the submission
directory. They may <strong>NOT</strong> contain absolute paths (paths that start with <code>/</code>)!
<code>txzchk</code> only checks the submission tarball so you must verify these details
yourself.
</p>
<p class="leftbar">
Make <strong>SURE</strong> your tarball does not reveal who you are! The <code>mkiocccentry(1)</code>
tool uses the v7 format. For instance you might try:
<strong>IMPORTANT REMINDER</strong>: <strong>MAKE SURE</strong> your tarball does not reveal who you are!
The <code>mkiocccentry(1)</code> tool uses the v7 format. For instance you might try:
</p>
<pre><code> tar --format=v7 -cJf foo.txz directory</code></pre>
<hr style="width:50%;text-align:left;margin-left:0">
@@ -1232,16 +1254,18 @@ for more help on ensuring you do have the most up to date release.
</p>
<p class="leftbar">
We recommend that you run <code>make</code> and then install the tools (and man pages) via
<code>make install</code> (as root or using <code>sudo(1)</code>) to help you run these tools from your
submission’s directory. The <code>make install</code> will install in <code>/usr/local</code>.
However, <strong>you do not have</strong> to install them, but in that case you’ll have to run it
from the toolkit’s directory or use the correct options to specify the path to
the necessary tools, and also specify the path to your files.
<code>make install</code> (as root or using <code>sudo(1)</code>) to help you run these tools from
your submission’s directory (or any other directory). The <code>make install</code> will
install in <code>/usr/local</code>. However, <strong>you do not have</strong> to install them, but in
that case you’ll have to run it from the toolkit’s directory or use the correct
options to specify the path to the necessary tools, and also specify the path to
your files.
</p>
<p class="leftbar">
These tools will link in the <code>jparse(3)</code> library; <code>chkentry(1)</code> uses the parser
to validate the <a href="https://www.json.org/json-en.html">JSON</a> but the other tools
use parts of the library as well.
These tools will link in the <code>jparse(3)</code> library and the <code>dbg</code> library and the
<code>dyn_array</code> library; <code>chkentry(1)</code> uses the JSON parser (<code>jparse</code>) to validate
and parse the <a href="https://www.json.org/json-en.html">JSON</a> but the other tools use
parts of the <code>jparse</code> utility functions as well.
</p>
<p class="leftbar">
If you run into a problem with one or more of these tools, <strong>PLEASE</strong> <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
@@ -1253,10 +1277,10 @@ FAQ on “<a href="../faq.html#mkiocccentry_bugs">mkiocccentry repo bugs</a>”.
</p>
<p class="leftbar">
At the risk of stating the obvious: submissions that violate <a href="#rule17">Rule
17</a> <strong>will be rejected</strong>, so <strong>be sure</strong> to use the latest release of the
17</a> <strong>WILL BE REJECTED</strong>, so <strong>BE SURE</strong> to use the latest release of the
<a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>, to form and test
your submission’s xz compressed tarball. Do <strong>NOT</strong> assume you have the most
recent release without pulling or downloading via GitHub and <strong>make sure</strong> you
recent release without pulling or downloading via GitHub and do <strong>MAKE SURE</strong> you
do this <strong>AFTER</strong> the <a href="../status.html">contest status</a> has changed to
<a href="../status.html#open">open</a>.
</p>
next/rules.md
+90 -65
View File
@@ -15,8 +15,8 @@ See our
FAQ on "[rules, guidelines, tools feedback](../faq.html#feedback)"
as well as our
FAQ on "[about asking questions](../faq.html#question)"
about these rules. You might also find the FAQ in general useful, especially the
FAQ on "[how to enter the IOCCC](../quick-start.html#enter)".
about these rules. You might also find the FAQ in general useful, as well as the
[quick start guide](../quick-start.html) and [how to register](register.html).
# The IOCCC is pending
@@ -50,15 +50,13 @@ Jump to: [top](#)
</div>
</div>
<p class="leftbar">
These [IOCCC rules](rules.html) are version **28.24 2025-02-12**.
These [IOCCC rules](rules.html) are version **28.25 2025-02-26**.
</p>
<p class="leftbar">
The <a href="rules.md" download="rules.md">markdown form of these rules</a>
is available for download.
The markdown form of these rules <a href="rules.md" download="rules.md">is
available for download</a>.
</p>
**IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
@@ -603,7 +601,7 @@ super-user, special owner, special group, etc.) are still **HIGHLY
DISCOURAGED**. We do not guarantee these functions will behave as
you expect on our test platforms. If your program needs special
permissions you **MUST** document this fact, and explain why
it is needed in your submissions `remarks.md` file.
it is needed in your submission's `remarks.md` file.
Jump to: [top](#)
@@ -757,11 +755,7 @@ Jump to: [top](#)
<p class="leftbar">
Each submission **MUST** be in the form of a xz compressed tarball.
The xz compressed tarball filename must be of the form:
</p>
``` <!---re-->
^submit.username-slot_num.[1-9][0-9]{9,}.txz$
```
`^submit.username-slot_num.[1-9][0-9]{9,}.txz$`.
<p class="leftbar">
... where _`username`_ is your IOCCC registration username **in the form of a
@@ -775,7 +769,7 @@ details), and where _`slot_num`_ is a single decimal digit integer
In particular, `username` is in the form of:
`xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx` where `'x'` is a hex digit in the range
of `[0-9a-f]`, 4 is the UUID version, and `N` is one of `8`, `9`, `a`, or `b`.
And yes, there is a 4 (UUID version 4) and variants `0x8`, `0x9`, `0xa` and
And yes, there is a 4 (UUID version 4) and the variants `0x8`, `0x9`, `0xa` and
`0xb` in there.
</p>
@@ -783,33 +777,19 @@ And yes, there is a 4 (UUID version 4) and variants `0x8`, `0x9`, `0xa` and
Your xz compressed tarball **MUST** contain, **at a minimum**, the following files:
</p>
* <p class="leftbar">`Makefile`</p>
* <p class="leftbar">`prog.c`</p>
* <p class="leftbar">`Makefile`</p>
* <p class="leftbar">`remarks.md`</p>
* <p class="leftbar">`.info.json`</p>
* <p class="leftbar">`.auth.json`</p>
* <p class="leftbar">`.info.json`</p>
<p class="leftbar">
The `.info.json` is generated by the `mkiocccentry(1)` tool. If not, and it is
not valid JSON or it does not pass the `chkentry(1)` tool, your submission
**WILL BE** rejected! If you do use `mkiocccentry(1)` and it fails to pass
`chkentry(1)` then you might wish to [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).
</p>
<p class="leftbar">
The `.auth.json` is generated by the `mkiocccentry(1)` tool. If not, and it is
not valid JSON or it does not pass the `chkentry(1)` tool, your submission
**WILL BE** rejected! If you do use `mkiocccentry(1)` and it fails to pass
`chkentry(1)` then you might wish to [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).
`prog.c` is of course your submission program.
</p>
<p class="leftbar">
The `Makefile` **MUST** be a **non**-empty file in **[GNU
Makefile](https://www.gnu.org/software/make/manual/make.html)** form. See the
Makefile](https://www.gnu.org/software/make/manual/make.html)** format. See the
[Makefile section in the guidelines](guidelines.html#makefile),
the
FAQ on "[submission Makefile](../faq.html#submission_makefiles)"
@@ -819,7 +799,7 @@ for help.
</p>
<p class="leftbar">
The `remarks.md` **MUST** be a **non**-empty file in markdown form
The `remarks.md` **MUST** be a **non**-empty file in markdown format
(`mkiocccentry(1)` only checks the file size but if you do not have any text in
it you still risk violating this rule). See also
[Rule 18](#rule18) and our
@@ -835,14 +815,47 @@ and the [CommonMark Spec](https://spec.commonmark.org/current/).
</p>
<p class="leftbar">
The xz compressed tarball file **MUST** be less than or equal to **3999971** octets in size.
The `.auth.json` file is created by `mkiocccentry(1)` and it holds information
about the author(s) of the submission. It will **ONLY** be looked at if your
submission wins but it **MUST** still be valid according to `chkentry(1)`.
</p>
<p class="leftbar">
The `.info.json` file is created by `mkiocccentry(1)` and it holds information
about the submission itself. It also **MUST** be valid according to
`chkentry(1)`.
</p>
<p class="leftbar">
For the complete `mkiocccentry(1)` process, see the
FAQ on the "[mkiocccentry process](../faq.html#mkiocccentry_process).
</p>
<p class="leftbar">
The tool performs a lot of checks, both directly and indirectly, and if it or
any other tool detects **ANY** problem, you are **HIGHLY** encouraged to fix it
and try again.
</p>
<p class="leftbar">
If you do use `mkiocccentry(1)` and you run into a problem, you might see the
FAQ on "[how to ask a question about the IOCCC rules, guidelines and
tools](../faq.html#questions)".
If you believe you have encountered a bug, feel free to open a bug report at the
[mkiocccentry repo issues
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
</p>
<p class="leftbar">
The xz compressed tarball file **MUST** be <= **3999971** octets in size.
</p>
<p class="leftbar">
When your submission's xz compressed tarball is uncompressed,
the total size of your submission: the sum of the size of the program,
hints, comments, build and info files **MUST** be less than or equal
to **28314624** octets (**27651K**) in size.
the total size of your submission (the sum of the size of the program,
hints, comments, build and info files) **MUST** be <=
**28314624** octets (**27651K**) in size.
</p>
<p class="leftbar">
@@ -881,7 +894,7 @@ Filenames in your entry (that is, not including the files generated by the
* <p class="leftbar">**NOT** have a leading **`/`**.</p>
* <p class="leftbar">**NOT** contain a path component of: **`.`** (that is, with
the exception of files generated by `mkiocccentry(1)` itself, it must have
**NO** **`.`**).</p>
**NO** **`.`** an **NO** dot file).</p>
* <p class="leftbar">**NOT** contain a path component of: **`..`** (that is,
**NO** **`..`**).</p>
* <p class="leftbar">Match the regular expression
@@ -901,8 +914,8 @@ authors (that will only be looked at if the submission wins).</p>
entry.</p>
<p class="leftbar">
The `chkentry(1)` tool will validate these two JSON files _prior to_ the tarball
being formed.
The `chkentry(1)` tool will validate these two JSON files, and do other checks
on your submission directory as well, _prior to_ forming the tarball.
</p>
<p class="leftbar">
@@ -912,18 +925,24 @@ permissions and `mkiocccentry(1)` does this for you. In particular: directories
`try.alt.sh`, if provided, **MUST** be `-r-xr-xr-x` (i.e. `0555`) and all other
files **MUST** be `-r--r--r--` (i.e. `0444`). If the files do not have these
permissions, your submission **WILL** be rejected for violating [Rule
17](#rule17)! If you do need different permissions, then see the
17](#rule17)! In addition to `mkiocccentry(1)` creating and copying the
directories and files with these modes, it also verifies them after the fact and
if they are not correct it is an **error**.
</p>
<p class="leftbar">
If you do need different permissions, then see the
FAQ on "[file permissions](../faq.html#file_perms)". Also keep in mind
[Rule 4](#rule4), [Rule 5](#rule5) and [Rule 21](#rule21).
</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
fail it is an error and `mkiocccentry(1)` will fail. In this case (it fails and
you used `mkiocccentry(1)`) it is very **possibly** a bug; please [report it as
a bug at the mkiocccentry issues
The `txzchk(1)` tool will also verify file/directory permissions (and many other
things) for you and so will `chkentry(1)` (along with validating the JSON files
and running semantics checks on them). If these checks fail it is an **error**
and `mkiocccentry(1)` will fail. In this case (it fails and you used
`mkiocccentry(1)`) 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).
</p>
@@ -937,7 +956,9 @@ possible there could be a problem and this poses a big risk of violating [Rule
<p class="leftbar">
The `fnamchk(1)`, which `txzchk(1)` executes, will verify that the
filename is correct.
filename is correct. But if you do package your tarball manually, and you have a
mismatch in what is in the tarball and the name, `txzchk(1)` will flag the
discrepancy as an error and exit with non-zero.
</p>
<p class="leftbar">
@@ -953,7 +974,7 @@ having your submission rejected for violating [Rule 17](#rule17)!
The maximum number of files your submission tarball may contain, not counting
the optional files (`prog.alt.c`, `try.sh`, `try.alt.sh`) and the mandatory
files (`prog.c`, `Makefile`, `remarks.md` plus the `mkiocccentry(1)` generated
files `.auth.json` and `.info.json`) is 31. This is defined in the macro
files `.auth.json` and `.info.json`), is 31. This is defined in the macro
`MAX_EXTRA_FILE_COUNT` in
[soup/limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). See the
@@ -966,7 +987,8 @@ If you do include a tarball that takes your extra files count over the maximum,
you **MUST** explain this in your `remarks.md` file! **PLEASE** do not include a
tarball with extra files for a test-suite; instead mention in your remarks that
you have extra files for a test-suite that can be included should your
submission win.
submission win. Of course if you don't need that many files for a test-suite you
are more than welcome to include those files in your submission.
</p>
<p class="leftbar">
@@ -976,14 +998,15 @@ created!
</p>
<p class="leftbar">
Tarballs **MUST** only create files and directories _under them_. They may
**NOT** contain absolute paths (paths that start with `/`)! `txzchk` only checks
the submission tarball so you must verify these details yourself.
Tarballs **MUST** only create files and directories _under_ the submission
directory. They may **NOT** contain absolute paths (paths that start with `/`)!
`txzchk` only checks the submission tarball so you must verify these details
yourself.
</p>
<p class="leftbar">
Make **SURE** your tarball does not reveal who you are! The `mkiocccentry(1)`
tool uses the v7 format. For instance you might try:
**IMPORTANT REMINDER**: **MAKE SURE** your tarball does not reveal who you are!
The `mkiocccentry(1)` tool uses the v7 format. For instance you might try:
</p>
``` <!---sh-->
@@ -1019,17 +1042,19 @@ for more help on ensuring you do have the most up to date release.
<p class="leftbar">
We recommend that you run `make` and then install the tools (and man pages) via
`make install` (as root or using `sudo(1)`) to help you run these tools from your
submission's directory. The `make install` will install in `/usr/local`.
However, **you do not have** to install them, but in that case you'll have to run it
from the toolkit's directory or use the correct options to specify the path to
the necessary tools, and also specify the path to your files.
`make install` (as root or using `sudo(1)`) to help you run these tools from
your submission's directory (or any other directory). The `make install` will
install in `/usr/local`. However, **you do not have** to install them, but in
that case you'll have to run it from the toolkit's directory or use the correct
options to specify the path to the necessary tools, and also specify the path to
your files.
</p>
<p class="leftbar">
These tools will link in the `jparse(3)` library; `chkentry(1)` uses the parser
to validate the [JSON](https://www.json.org/json-en.html) but the other tools
use parts of the library as well.
These tools will link in the `jparse(3)` library and the `dbg` library and the
`dyn_array` library; `chkentry(1)` uses the JSON parser (`jparse`) to validate
and parse the [JSON](https://www.json.org/json-en.html) but the other tools use
parts of the `jparse` utility functions as well.
</p>
<p class="leftbar">
@@ -1042,10 +1067,10 @@ FAQ on "[mkiocccentry repo bugs](../faq.html#mkiocccentry_bugs)".
</p>
<p class="leftbar">At the risk of stating the obvious: submissions that violate [Rule
17](#rule17) **will be rejected**, so **be sure** to use the latest release of the
17](#rule17) **WILL BE REJECTED**, so **BE SURE** to use the latest release of the
[mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), to form and test
your submission's xz compressed tarball. Do **NOT** assume you have the most
recent release without pulling or downloading via GitHub and **make sure** you
recent release without pulling or downloading via GitHub and do **MAKE SURE** you
do this **AFTER** the [contest status](../status.html) has changed to
[open](../status.html#open).
</p>