Update FAQ and rules for mkiocccentry
Additional things were added to the process (and as for the rules it notes that remarks.md is only checked for size > 0, not that it has content).
This commit is contained in:
Cody Boone Ferguson committed
1 parent
f5bf279807
commit
c6e1c09401
4 files changed
+108
-66
No files matched your search
@@ -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.5 2025-02-07</strong>.</p>
|
||||
<p>This is FAQ version <strong>28.2.6 2025-02-08</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>
|
||||
@@ -1463,9 +1463,10 @@ 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 a filename or directory name is not a sane relative path, not allowed
|
||||
or will not be added for some reason, it will be added to a relevant list to show to
|
||||
the user later, to let them know it is ignored (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>
|
||||
@@ -1478,49 +1479,65 @@ details).</li>
|
||||
<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.
|
||||
<li>The user is presented with lists of files, symlinks and directories found.
|
||||
<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
|
||||
<li>Symlinks are ignored and may not be included. You will be warned about
|
||||
this.</li>
|
||||
<li>Certain filenames (such as <code>README.md</code>, <code>index.html</code> and various others)
|
||||
are forbidden and are not allowed. <code>mkiocccentry(1)</code> will warn and let you
|
||||
know about this.</li>
|
||||
<li>Certain directories like <code>.git</code>, <code>CVS</code> and other RCS related 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>
|
||||
a list of these directories.</li>
|
||||
<li>No file or directory starting with <code>.</code> will be allowed.</li>
|
||||
<li>List of directories that will be made.</li>
|
||||
<li>List of required and non-required files that will be added.</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.
|
||||
<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code> (created prior to traversing the
|
||||
<code>topdir</code>), making sure to keep the files in the correct directory.
|
||||
<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>
|
||||
<li>Directories <strong>MUST</strong> be (and will be made) with mode <code>0755</code>.</li>
|
||||
<li><code>try.sh</code> and <code>try.alt.sh</code> <strong>MUST</strong> be (and will be copied as) executable (in
|
||||
particular: mode <code>0555</code>).</li>
|
||||
<li>Other files MUST be (and will be copied as) mode <code>0444</code>.</li>
|
||||
<li><code>txzchk(1)</code> verifies these modes (and much more).</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>
|
||||
<li>If this fails it is not an error but you are warned about it (even so, see
|
||||
<a href="next/rules.html#rule20">Rule 20</a>).</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 <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> are missing (or not readable
|
||||
regular files) it is an error.</li>
|
||||
<li><code>iocccsize(1)</code> (via the <code>mkiocccentry(1)</code> function <code>check_prog_c()</code>) will
|
||||
be run on your <code>prog.c</code>, allowing you to override any warnings; if you do not
|
||||
override an issue flagged it is an error but if warnings from <code>check_prog_c()</code>
|
||||
are ignored you risk violating the <a href="next/rules.html">Rules</a>, including <a href="next/rules.html#rule2">Rule
|
||||
2</a>.</li>
|
||||
<li><code>check_Makefile()</code> will be run on <code>Makefile</code>; if it is a non-readable or
|
||||
empty file it is an error but otherwise you may override any warnings
|
||||
(risking violating the <a href="next/rules.html">Rules</a>, especially <a href="next/rules.html#rule17">Rule
|
||||
17</a> and <a href="next/rules.html#rule20">Rule 20</a>).</li>
|
||||
<li><code>check_remarks_md()</code> will be run on your <code>remarks.m</code>; if it is not a
|
||||
regular readable file or it is empty it is an error. Otherwise it will
|
||||
proceed. Note it does not check that there is any text in the file, just
|
||||
that the file size is not 0.</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>
|
||||
details, and for even more details see the comments in the jparse function
|
||||
<code>sane_relative_path()</code> in the
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c">jparse/util.c</a>
|
||||
file at the <a href="https://github.com/ioccc-src/mkiocccentry%5D">mkiocccentry repo</a> (this
|
||||
comes from the <a href="https://github.com/xexyl/jparse/">jparse repo</a>).</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>
|
||||
@@ -1532,7 +1549,8 @@ details).</li>
|
||||
<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>Report on files that were copied in (3) and directories made 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
|
||||
@@ -1559,7 +1577,8 @@ for more details on the tools that <code>mkiocccentry</code> either executes dir
|
||||
indirectly as part of the packaging process, especially if you wish to run one
|
||||
or more of these tools manually.</p>
|
||||
<p>See also the <a href="next/guidelines.html">Guidelines</a> and the <a href="next/rules.html">Rules</a>
|
||||
(and in particular <a href="next/rules.html#rule17">Rule 17</a>).</p>
|
||||
(especially <a href="next/rules.html#rule2">Rule 2</a>, <a href="next/rules.html#rule17">Rule
|
||||
17</a>, <a href="next/rules.html#rule20">Rule 20</a>).</p>
|
||||
<p>Jump to: <a href="#">top</a></p>
|
||||
<div id="txzchk">
|
||||
<div id="tarball">
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# IOCCC FAQ Table of Contents
|
||||
|
||||
This is FAQ version **28.2.5 2025-02-07**.
|
||||
This is FAQ version **28.2.6 2025-02-08**.
|
||||
|
||||
|
||||
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
|
||||
@@ -1283,10 +1283,11 @@ The `mkiocccentry(1)` tool performs the following steps:
|
||||
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).
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
|
||||
* If a filename or directory name is not a sane relative path, not allowed
|
||||
or will not be added for some reason, it will be added to a relevant list to show to
|
||||
the user later, to let them know it is ignored (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)).
|
||||
@@ -1298,42 +1299,58 @@ to the submission directory.
|
||||
`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
|
||||
2. The user is presented with lists of files, symlinks and directories found.
|
||||
* Symlinks are ignored and may not be included. You will be warned about
|
||||
this.
|
||||
* Certain filenames (such as `README.md`, `index.html` and various others)
|
||||
are forbidden and are not allowed. `mkiocccentry(1)` will warn and let you
|
||||
know about this.
|
||||
* Certain directories like `.git`, `CVS` and other RCS related 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.
|
||||
a list of these directories.
|
||||
* No file or directory starting with `.` will be allowed.
|
||||
* List of directories that will be made.
|
||||
* List of required and non-required files that will be added.
|
||||
* 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`).
|
||||
`workdir/submit.USERNAME-SLOT.TIMESTAMP` (created prior to traversing the
|
||||
`topdir`), making sure to keep the files in the correct directory.
|
||||
* 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.
|
||||
* Directories **MUST** be (and will be made) with mode `0755`.
|
||||
* `try.sh` and `try.alt.sh` **MUST** be (and will be copied as) executable (in
|
||||
particular: mode `0555`).
|
||||
* Other files MUST be (and will be copied as) mode `0444`.
|
||||
* `txzchk(1)` verifies these modes (and much more).
|
||||
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 this fails it is not an error but you are warned about it (even so, see
|
||||
[Rule 20](next/rules.html#rule20)).
|
||||
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 `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
|
||||
regular files) it is an error.
|
||||
* `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
|
||||
be run on your `prog.c`, allowing you to override any warnings; if you do not
|
||||
override an issue flagged it is an error but if warnings from `check_prog_c()`
|
||||
are ignored you risk violating the [Rules](next/rules.html), including [Rule
|
||||
2](next/rules.html#rule2).
|
||||
* `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
|
||||
empty file it is an error but otherwise you may override any warnings
|
||||
(risking violating the [Rules](next/rules.html), especially [Rule
|
||||
17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
|
||||
* `check_remarks_md()` will be run on your `remarks.m`; if it is not a
|
||||
regular readable file or it is empty it is an error. Otherwise it will
|
||||
proceed. Note it does not check that there is any text in the file, just
|
||||
that the file size is not 0.
|
||||
* 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).
|
||||
details, and for even more details see the comments in the jparse function
|
||||
`sane_relative_path()` in the
|
||||
[jparse/util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/util.c)
|
||||
file at the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry]) (this
|
||||
comes from the [jparse repo](https://github.com/xexyl/jparse/)).
|
||||
* 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)).
|
||||
@@ -1344,7 +1361,8 @@ required and non-required files.
|
||||
`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.
|
||||
7. Report on files that were copied in (3) and directories made 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
|
||||
@@ -1374,7 +1392,8 @@ indirectly as part of the packaging process, especially if you wish to run one
|
||||
or more of these tools manually.
|
||||
|
||||
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
|
||||
(and in particular [Rule 17](next/rules.html#rule17)).
|
||||
(especially [Rule 2](next/rules.html#rule2), [Rule
|
||||
17](next/rules.html#rule17), [Rule 20](next/rules.html#rule20)).
|
||||
|
||||
Jump to: [top](#)
|
||||
|
||||
|
||||
+4
-2
@@ -461,7 +461,7 @@ 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.21 2025-02-03</strong>.
|
||||
These <a href="rules.html">IOCCC rules</a> are version <strong>28.22 2025-02-08</strong>.
|
||||
</p>
|
||||
<p class="leftbar">
|
||||
The <a href="rules.md" download="rules.md">markdown form of these rules</a>
|
||||
@@ -1043,7 +1043,9 @@ 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. See also
|
||||
The <code>remarks.md</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in markdown form
|
||||
(<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
|
||||
FAQ on “<a href="../faq.html#remarks_md">remarks.md</a>”
|
||||
and our
|
||||
|
||||
+4
-2
@@ -53,7 +53,7 @@ Jump to: [top](#)
|
||||
|
||||
|
||||
<p class="leftbar">
|
||||
These [IOCCC rules](rules.html) are version **28.21 2025-02-03**.
|
||||
These [IOCCC rules](rules.html) are version **28.22 2025-02-08**.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
@@ -819,7 +819,9 @@ for help.
|
||||
</p>
|
||||
|
||||
<p class="leftbar">
|
||||
The `remarks.md` **MUST** be a **non**-empty file in markdown form. See also
|
||||
The `remarks.md` **MUST** be a **non**-empty file in markdown form
|
||||
(`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
|
||||
FAQ on "[remarks.md](../faq.html#remarks_md)"
|
||||
and our
|
||||
|
||||
Reference in new issue
Block a user