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

experiment to move much of Rule 17 text into an FAQ

Browse Source 
In order simplify the write-up of the actual Rule 17
into a new FAQ 1.8.  The somewhat shorted Rule 17 text
now refers to checks performed by tools, encourages
their use, discourages their misuse (overriding limits),
and is easier to read: we think.
This commit is contained in:
Landon Curt Noll committed 2025-03-01 01:42:21 -08:00
1 parent 6f06d1f441
commit bf6d0a3574
7 files changed
+886 -733
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.md
+400 -1
View File
@@ -27,6 +27,7 @@ This is FAQ version **28.2.12 2025-02-28**.
- **Q 1.5**: <a class="normal" href="#mkiocccentry_test">How can I check if my submission passes tests without having to answer questions?</a>
- **Q 1.6**: <a class="normal" href="#extra-files">How may I include additional files beyond the max allowed?</a>
- **Q 1.7**: <a class="normal" href="#ai">May I use AI, Virtual coding assistants, or similar tools to write my submission?</a>
- **Q 1.8**: <a class="normal" href="#rule17">What are the details behind Rule 17?</a>
## 2. [IOCCC Judging process](#judging_proceess)
@@ -818,7 +819,7 @@ tarball needs to pass these tests.
Please pay careful attention to [Rule 17](next/rules.html#rule17) and in
particular the part about the [maximum number of files per
submission](next/rules.html#max-files), which not only discusses the maximum
submission](#max-files), which not only discusses the maximum
number of files (including extra files) but also specific rules you must follow
if you do include a tarball. Not following these points puts you at great risk
of violating [Rule 17](next/rules.html#rule17)!
@@ -856,6 +857,404 @@ as how you them to help write you submission in your `remarks.md` file.
Jump to: [top](#)
<div id="rule17">
### Q 1.8: What are details behind Rule 17?
</div>
The following are the details behind [Rule 17](next/rules.html#rule17).
### TL;DR Rule 17 - Use `mkiocccentry(1)`
<p class="leftbar">
This is a **COMPLEX** rule. **Violating this rule will cause your submission to REJECTED!**
To help you avoid such a rejection, you are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool,
based on the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry),
to form your submission's xz compressed tarball.
</p>
<p class="leftbar">
The [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
contains **IMPORTANT** tools and libraries such as:
</p>
* <p class="leftbar">`chkentry(1)`</p>
* <p class="leftbar">`iocccsize(1)`</p>
* <p class="leftbar">`mkiocccentry(1)`</p>
* <p class="leftbar">`txzchk(1)`</p>
* <p class="leftbar">`fnamchk(1)`</p>
* <p class="leftbar">`jparse(1)` (and other tools) and `jparse(3)` (which `chkentry(1)` uses)</p>
<p class="leftbar">
The above mentioned tools will help you verify that your submission
conforms to [Rule 17](next/rules.html#rule17).
</p>
<p class="leftbar">
Each above mentioned tool has a `-h` option that provides command line help. For
additional details of each tool, see its man page, and in some cases, the [IOCCC
guidelines](next/guidelines.html).
</p>
<p class="leftbar">
There is no need to use `jparse(1)` but the `jparse(3)` library
library will be linked when compiling the tools as they use various functions
provided by it, and `chkentry` uses the JSON parser API as well.
</p>
<p class="leftbar">
Of course you **may** invoke `jparse(1)` if you wish to validate a JSON file but
the only JSON files you might want to validate for the IOCCC are validated
by `chkentry(1)`, and that is what you should use to make sure you conform to
this rule.
</p>
<p class="leftbar">
The maximum number of **extra files** is 31. See the [maximum number of extra
files section](#max-files) below for finer details and the
FAQ on "[including additional files](#extra-files)"
if you need to include more files than this maximum.
</p>
<p class="leftbar">
Extra files are defined as files that are not the required files (`prog.c`,
`Makefile`, `remarks.md` and the two generated by `mkiocccentry(1)` `.info.json`
and `.auth.json`) and files that are also not the optional files (`try.sh`,
`prog.alt.c` and `try.alt.sh`).
</p>
Jump to: [top](#)
### Rule 17 - The COMPLEX details
<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:
`^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
[UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)** (see
[RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562) for
details), and where _`slot_num`_ is a single decimal digit integer
(i.e., >= `0` and < `9`).
</p>
<p class="leftbar">
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 the variants `0x8`, `0x9`, `0xa` and
`0xb` in there.
</p>
<p class="leftbar">
Your xz compressed tarball **MUST** contain, **at a minimum**, the following files:
</p>
* <p class="leftbar">`prog.c`</p>
* <p class="leftbar">`Makefile`</p>
* <p class="leftbar">`remarks.md`</p>
* <p class="leftbar">`.auth.json`</p>
* <p class="leftbar">`.info.json`</p>
<p class="leftbar">
`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)** format. See the
[Makefile section in the guidelines](next/guidelines.html#makefile),
the
FAQ on "[submission Makefile](#submission_makefiles)"
and the
FAQ on "[Makefile compatibility](#make_compatibility)"
for help.
</p>
<p class="leftbar">
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](next/rules.html#rule18) and our
FAQ on "[remarks.md](#remarks_md)"
and our
FAQ on "[markdown](#markdown)"
and our [markdown guidelines](markdown.html).
</p>
<p class="leftbar">
See also the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide
and the [CommonMark Spec](https://spec.commonmark.org/current/).
</p>
<p class="leftbar">
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](#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](#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 <=
**28314624** octets (**27651K**) in size.
</p>
<p class="leftbar">
Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
the [guidelines](next/guidelines.html) for more details on this tool.
</p>
<p class="leftbar">
**IMPORTANT**: Make **SURE** you have the most recent version of the
`mkiocccentry` toolkit! Not doing so will put you at a great risk of violating
this rule! See the
FAQ on "[obtaining the mkiocccentry toolkit](#mkiocccentry)"
for more details.
</p>
<p class="leftbar">
You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your
submission's xz compressed tarball. See the [guidelines](next/guidelines.html) for
more details on this tool and the [mkiocccentry
repo](https://github.com/ioccc-src/mkiocccentry).
</p>
<p class="leftbar">
Your entry may have subdirectories, depending on the depth and total length of
the filenames. Certain directories like `.git`, `RCCS`, `CVS` and `.svn` are
skipped. For more information, see the [guidelines](next/guidelines.html).
</p>
<p class="leftbar">
Filenames in your entry (that is, not including the files generated by the
`mkiocccentry(1)` tool or the tools it or any other tool invokes) **MUST**:
</p>
* <p class="leftbar">Be <= **38** characters in length.</p>
* <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** **`.`** 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
`^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$` (again, excluding files generated by
`mkiocccentry(1)`).</p>
* <p class="leftbar">**NOT** be a directory depth > 4.</p>
* <p class="leftbar">**NOT** have a total **path** length > 99 characters.</p>
<p class="leftbar">
The submission tarball created by `mkiocccentry(1)` **MUST** have
the additional files that are generated by the `mkiocccentry(1)` tool:
</p>
* <p class="leftbar">`.auth.json` which contains information about the author or
authors (that will only be looked at if the submission wins).</p>
* <p class="leftbar">`.info.json` which contains information about the
entry.</p>
<p class="leftbar">
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">
Files and directories in your submission tarball **MUST** be specific
permissions and `mkiocccentry(1)` does this for you. In particular: directories
**MUST** be `drwxr-xr-x` (i.e. `0755`), the optional files, `try.sh` or
`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](next/rules.html#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](#file_perms)". Also keep in mind
[Rule 4](next/rules.html#rule4), [Rule 5](next/rules.html#rule5) and [Rule 21](next/rules.html#rule21).
</p>
<p class="leftbar">
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>
<p class="leftbar">
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 poses a big risk of violating [Rule
17](next/rules.html#rule17).
</p>
<p class="leftbar">
The `fnamchk(1)`, which `txzchk(1)` executes, will verify that the
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">
These checks **MUST PASS**. If they do not you stand a significant chance of
having your submission rejected for violating [Rule 17](next/rules.html#rule17)!
</p>
<div id="max-files">
#### Maximum number of files per submission
</div>
<p class="leftbar">
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
`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
FAQ on "[how to include additional files](#extra-files)"
if you need to include more files.
</p>
<p class="leftbar">
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. 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
itself, then `make clobber` **MUST** remove everything that the extraction
created!
</p>
<p class="leftbar">
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">
**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-->
tar --format=v7 -cJf foo.txz directory
```
<hr style="width:50%;text-align:left;margin-left:0">
<p class="leftbar">
**IMPORTANT**: where [Rule 17](next/rules.html#rule17) and the tools from the latest
release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
conflict, the [IOCCC judges](judges.html) will use their best judgment which
is likely to favor [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) code.
</p>
<p class="leftbar">
This means you should **MAKE SURE** that you use `mkiocccentry(1)` to
package your submission; `mkiocccentry(1)` will run the above mentioned tools
(that do not act on the tarball) **before** creating the tarball and after the
tarball is created it will then verify that the tarball is okay by running
`txzchk(1)` on it. If any step fails it is an error and submitting the
submission will result in violating this rule.
</p>
<p class="leftbar">
**MAKE SURE** you use the correct release of the repository; you should do this
**AFTER** the contest opens (pull any changes or if you prefer download the
repository via the download option at GitHub). See the
FAQ on "[obtaining mkiocccentry](#obtaining_mkiocccentry)"
for more help on ensuring you do have the most up to date release.
</p>
<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 (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 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">
If you run into a problem with one or more of these tools, **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),
**making sure to run `bug_report.sh`**. See the [guidelines](next/guidelines.html)
for help here and also read our
FAQ on "[mkiocccentry repo bugs](#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
[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 do **MAKE SURE** you
do this **AFTER** the [contest status](status.html) has changed to
[open](#open).
</p>
Jump to: [top](#)
<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">