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

Update FAQ about new mkiocccentry process

Browse Source
This commit is contained in:
Cody Boone Ferguson committed 2025-02-07 11:58:19 -08:00
1 parent d2c6b42078
commit f5bf279807
2 files changed
+190 -18
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+99 -9
View File
@@ -425,7 +425,7 @@
<!-- BEFORE: 1st line of markdown file: faq.md -->
<h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1>
<p>This is FAQ version <strong>28.2.4 2025-02-03</strong>.</p>
<p>This is FAQ version <strong>28.2.5 2025-02-07</strong>.</p>
<h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter_questions">Entering the IOCCC: the bare minimum you need to know</a></h2>
<ul>
<li><strong>Q 0.0</strong>: <a class="normal" href="#enter">How can I enter the IOCCC?</a></li>
@@ -714,12 +714,12 @@ subdirectory), as it needs to be empty.</p>
<p>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>The <code>mkiocccentry(1)</code> tool will ask you for information about your
be the <em>subdirectory</em> with your submission’s files</strong>.
The <code>mkiocccentry(1)</code> tool will also ask you for information about your
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 briefly
mentioned earlier, and as described in the
“<a href="#mkiocccentry_details">finer details</a>” section.</p>
submission wins), run some tests and run a number of other tools, as
mentioned above, and as described in the “<a href="#mkiocccentry_details">finer
details</a>” section.</p>
<p>See also the
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md">mkiocccentry repo FAQ</a>
for more up to date information on downloading, compiling, and related FAQ information.</p>
@@ -1392,7 +1392,9 @@ Jump to: <a href="#">top</a>
<div id="mkiocccentry_checks">
<h3 id="q-3.0-what-sort-of-checks-does-the-mkiocccentry-tool-perform">Q 3.0: What sort of checks does the mkiocccentry tool perform?</h3>
</div>
<p><code>mkiocccentry(1)</code> will check and warn about the following conditions:</p>
<p>In addition to the checks in the <a href="#mkiocccentry_process">mkiocccentry process</a>
described below, <code>mkiocccentry(1)</code> will check and warn about the following
conditions:</p>
<ul>
<li>If the files do not exist, are not regular files or cannot be read.</li>
<li>If <code>prog.c</code> violates <a href="next/rules.html#rule2">Rule 2</a> (see
@@ -1412,8 +1414,9 @@ Jump to: <a href="#">top</a>
<li>If the <code>Makefile</code> does not have a <code>clean</code> rule.</li>
<li>If the <code>Makefile</code> does not have a <code>clobber</code> rule.</li>
<li>If the <code>Makefile</code> does not have a <code>try</code> rule.</li>
<li>If the <code>remarks.md</code> is empty.</li>
</ul>
<p>If your <code>Makefile</code> is empty or <code>remarks.md</code> is empty it is an error and you will
have to fix it.</p>
<p>Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
they are correct, are:</p>
<ul>
@@ -1448,8 +1451,95 @@ has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (
<li>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>.</li>
<li>An <em>author handle</em> is repeated.</li>
<li>The output of <code>ls</code> on the submission directory is incorrect.</li>
</ul>
<div id="mkiocccentry_process">
<h4 id="mkiocccentry-process"><code>mkiocccentry</code> process</h4>
</div>
<p>The <code>mkiocccentry(1)</code> tool performs the following steps:</p>
<ol start="0" type="1">
<li>Change to the <code>topdir</code>.</li>
<li>Traverses the directory, gathering lists of ignored files and files to copy
to the submission directory.
<ul>
<li>If the depth is too deep it is an error (see <code>MAX_PATH_DEPTH</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If a file is not a sane relative path it is an error (see the
<a href="next/rules.html#">Rules</a> and <a href="next/guidelines.html">Guidelines</a> for more
details).</li>
<li>If the path length (all components) are too long it is an error (see
<code>MAX_PATH_LEN</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If a filename is too long it is an error (see <code>MAX_FILENAME_LEN</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If a directory is not readable it is an error.</li>
<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are not found it is an error.</li>
<li>If too many files that are 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> are found, it is an error (see
<code>MAX_EXTRA_FILE_COUNT</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
</ul></li>
<li>The user is presented with lists of files (including symlinks) and
directories that were ignored as well as files and directories to be added, both
required and non-required files.
<ul>
<li>Symlinks are ignored and may not be included.</li>
<li>Certain filenames are forbidden and are not allowed. <code>mkiocccentry(1)</code>
will warn let you know about this. If you do not confirm that this is okay
it is an error.</li>
<li>Certain directories like <code>.git</code>, <code>CVS</code> and other RCS directories are not
allowed but are ignored (and not descended into). You will be presented with
a list of these directories and be asked to confirm it as well.</li>
<li>The user is asked to verify each list, including the list of files to be
added, and if the user says it is not OK the program will abort.</li>
</ul></li>
<li>The non-ignored files are copied under
<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code>, in the correct subdirectories.
<ul>
<li>As it copies <code>prog.c</code> it runs <code>iocccsize(1)</code> and other tests on it,
allowing you to override issues.</li>
<li>As it copies <code>Makefile</code> it runs tests on it, allowing you to override
certain issues. <code>Makefile</code> may not be empty.</li>
<li>As it copies <code>remarks.m</code> it checks that it is not empty (if it is empty it
is an error). <code>remarks.md</code> may not be empty.</li>
<li>Only <code>try.sh</code> and <code>try.alt.sh</code> may be executable (mode <code>0555</code>).</li>
<li>Directories are made prior to the copying of the files.</li>
<li>Directories will be made with mode <code>0755</code>.</li>
<li>Other files are mode <code>0444</code>.</li>
<li><code>txzchk(1)</code> verifies these.</li>
</ul></li>
<li><code>cd submit.USERNAME-SLOT.TIMESTAMP</code>.</li>
<li><code>make -f Makefile clobber</code>.
<ul>
<li>If this fails it is not an error but you are warned about it; if the
Makefile does not exist it is an error.</li>
</ul></li>
<li>Traverse the new tree from <code>.</code>, collecting files in the submission directory.
<ul>
<li>If an invalid file or directory is found it is an error.</li>
<li>If the depth is too deep it is an error.</li>
<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are missing it is an error.</li>
<li>If a file is not a sane relative path it is an error (see the
<a href="next/rules.html#">Rules</a> and <a href="next/guidelines.html">Guidelines</a> for more
details).</li>
<li>If the path length (all components) are too long it is an error (see
<code>MAX_PATH_LEN</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If a filename is too long it is an error (see <code>MAX_FILENAME_LEN</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If a directory is not readable it is an error.</li>
<li>If too many files that are 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> are found, it is an error (see
<code>MAX_EXTRA_FILE_COUNT</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
</ul></li>
<li>Report on files that were copied in (3) but are now gone: asking the user to verify.</li>
<li>Present the list of non-dot files that remain and ask the user to confirm.</li>
<li>Create the <code>.info.json</code> and <code>.auth.json</code> files, running <code>chkenry(1)</code> on each.</li>
<li>List the submission directory contents, asking the user once again to verify
everything is okay.</li>
<li>Form the tarball and run <code>txzchk(1)</code> on it.</li>
</ol>
<p>If any of the steps fail or if the user says something is not okay, it aborts.</p>
<p>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="next/rules.html">rules</a> state, each of these tools has a <code>-h</code> option.</p>
faq.md
+91 -9
View File
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
This is FAQ version **28.2.4 2025-02-03**.
This is FAQ version **28.2.5 2025-02-07**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -339,12 +339,11 @@ 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**.
The `mkiocccentry(1)` tool will ask you for information about your
The `mkiocccentry(1)` tool will also ask you for information about your
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 briefly
mentioned earlier, and as described in the
"[finer details](#mkiocccentry_details)" section.
submission wins), run some tests and run a number of other tools, as
mentioned above, and as described in the "[finer
details](#mkiocccentry_details)" section.
See also the
[mkiocccentry repo FAQ](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md)
@@ -1213,7 +1212,9 @@ Jump to: [top](#)
### Q 3.0: What sort of checks does the mkiocccentry tool perform?
</div>
`mkiocccentry(1)` will check and warn about the following conditions:
In addition to the checks in the [mkiocccentry process](#mkiocccentry_process)
described below, `mkiocccentry(1)` will check and warn about the following
conditions:
- If the files do not exist, are not regular files or cannot be read.
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
@@ -1233,7 +1234,9 @@ Jump to: [top](#)
- If the `Makefile` does not have a `clean` rule.
- If the `Makefile` does not have a `clobber` rule.
- If the `Makefile` does not have a `try` rule.
- If the `remarks.md` is empty.
If your `Makefile` is empty or `remarks.md` is empty it is an error and you will
have to fix it.
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
they are correct, are:
@@ -1269,7 +1272,86 @@ has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
- An _author handle_, if the default is not accepted, does
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
- An _author handle_ is repeated.
- The output of `ls` on the submission directory is incorrect.
<div id="mkiocccentry_process">
#### `mkiocccentry` process
</div>
The `mkiocccentry(1)` tool performs the following steps:
0. Change to the `topdir`.
1. Traverses the directory, gathering lists of ignored files and files to copy
to the submission directory.
* If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a file is not a sane relative path it is an error (see the
[Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
details).
* If the path length (all components) are too long it is an error (see
`MAX_PATH_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a directory is not readable it is an error.
* If `prog.c`, `Makefile` or `remarks.md` are not found it is an error.
* If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
`try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
`MAX_EXTRA_FILE_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
2. The user is presented with lists of files (including symlinks) and
directories that were ignored as well as files and directories to be added, both
required and non-required files.
* Symlinks are ignored and may not be included.
* Certain filenames are forbidden and are not allowed. `mkiocccentry(1)`
will warn let you know about this. If you do not confirm that this is okay
it is an error.
* Certain directories like `.git`, `CVS` and other RCS directories are not
allowed but are ignored (and not descended into). You will be presented with
a list of these directories and be asked to confirm it as well.
* The user is asked to verify each list, including the list of files to be
added, and if the user says it is not OK the program will abort.
3. The non-ignored files are copied under
`workdir/submit.USERNAME-SLOT.TIMESTAMP`, in the correct subdirectories.
* As it copies `prog.c` it runs `iocccsize(1)` and other tests on it,
allowing you to override issues.
* As it copies `Makefile` it runs tests on it, allowing you to override
certain issues. `Makefile` may not be empty.
* As it copies `remarks.m` it checks that it is not empty (if it is empty it
is an error). `remarks.md` may not be empty.
* Only `try.sh` and `try.alt.sh` may be executable (mode `0555`).
* Directories are made prior to the copying of the files.
* Directories will be made with mode `0755`.
* Other files are mode `0444`.
* `txzchk(1)` verifies these.
4. `cd submit.USERNAME-SLOT.TIMESTAMP`.
5. `make -f Makefile clobber`.
* If this fails it is not an error but you are warned about it; if the
Makefile does not exist it is an error.
6. Traverse the new tree from `.`, collecting files in the submission directory.
* If an invalid file or directory is found it is an error.
* If the depth is too deep it is an error.
* If `prog.c`, `Makefile` or `remarks.md` are missing it is an error.
* If a file is not a sane relative path it is an error (see the
[Rules](next/rules.html#) and [Guidelines](next/guidelines.html) for more
details).
* If the path length (all components) are too long it is an error (see
`MAX_PATH_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a filename is too long it is an error (see `MAX_FILENAME_LEN` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If a directory is not readable it is an error.
* If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
`try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
`MAX_EXTRA_FILE_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
7. Report on files that were copied in (3) but are now gone: asking the user to verify.
8. Present the list of non-dot files that remain and ask the user to confirm.
9. Create the `.info.json` and `.auth.json` files, running `chkenry(1)` on each.
10. List the submission directory contents, asking the user once again to verify
everything is okay.
11. Form the tarball and run `txzchk(1)` on it.
If any of the steps fail or if the user says something is not okay, it aborts.
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the