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

Merge pull request #90 from xexyl/mkiocccentry-process-faq

Browse Source
This commit is contained in:
Landon Curt Noll authored and GitHub committed 2025-02-10 14:13:35 -08:00
2 parents 478f8a66bf 1c5f14f3e0
commit 83688ed65b
18 files changed
+885 -313
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

SECURITY.html
+2 -2
View File
@@ -450,8 +450,8 @@ interface</a>
instead.</p>
<h1 id="important-disclaimer">Important Disclaimer</h1>
<p>IOCCC code is for <strong>educational and entertainment purposes only</strong>. We do <strong>NOT</strong>
recommend installing any winning IOCCC entry code. Use code found the IOCCC repo
and in the IOCCC web site <strong>at your own risk!</strong></p>
recommend installing any winning IOCCC entry code. Use code found in the IOCCC repo
and in the IOCCC website <strong>at your own risk!</strong></p>
<p>The <a href="index.html">IOCCC</a> and the <a href="judges.html">IOCCC judges</a> DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THEY BE LIABLE FOR ANY SPECIAL,
SECURITY.md
+2 -2
View File
@@ -35,8 +35,8 @@ instead.
# Important Disclaimer
IOCCC code is for **educational and entertainment purposes only**. We do **NOT**
recommend installing any winning IOCCC entry code. Use code found the IOCCC repo
and in the IOCCC web site **at your own risk!**
recommend installing any winning IOCCC entry code. Use code found in the IOCCC repo
and in the IOCCC website **at your own risk!**
The [IOCCC](index.html) and the [IOCCC judges](judges.html) DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
contact.html
+3 -3
View File
@@ -444,11 +444,11 @@ FAQ on “<a href="faq.html#pull_request">submitting a pull request</a>”.</p>
<p>If you are trying to:</p>
<ul>
<li><strong>Report a bug in an IOCCC winning entry</strong> - See our
FAQ on “<a href="faq.html#report_bug">report entry bug</a>”</li>
FAQ on “<a href="faq.html#report_bug">reporting an entry bug</a>”</li>
<li><strong>Report an IOCCC website problem</strong> - See our
FAQ on “<a href="faq.html#report_web_problem">report website problem</a>”</li>
FAQ on “<a href="faq.html#report_web_problem">reporting a website problem</a>”</li>
<li><strong>Report a broken or wrong web link</strong> - See our
FAQ on “<a href="faq.html#fix_link">report broken link</a>”</li>
FAQ on “<a href="faq.html#fix_link">reporting a broken link</a>”</li>
</ul>
<p>In general, unless you have a fix, if you want to report something, you should instead first look at the <a href="https://github.com/ioccc-src/winner/issues">IOCCC
issues</a> to see if the
contact.md
+3 -3
View File
@@ -20,11 +20,11 @@ FAQ on "[submitting a pull request](faq.html#pull_request)".
If you are trying to:
* **Report a bug in an IOCCC winning entry** - See our
FAQ on "[report entry bug](faq.html#report_bug)"
FAQ on "[reporting an entry bug](faq.html#report_bug)"
* **Report an IOCCC website problem** - See our
FAQ on "[report website problem](faq.html#report_web_problem)"
FAQ on "[reporting a website problem](faq.html#report_web_problem)"
* **Report a broken or wrong web link** - See our
FAQ on "[report broken link](faq.html#fix_link)"
FAQ on "[reporting a broken link](faq.html#fix_link)"
In general, unless you have a fix, if you want to report something, you should instead first look at the [IOCCC
issues](https://github.com/ioccc-src/winner/issues) to see if the
faq.html
+243 -43
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.2 2025-01-30</strong>.</p>
<p>This is FAQ version <strong>28.2.8 2025-02-10</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>
@@ -440,6 +440,7 @@
<li><strong>Q 0.3</strong>: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a></li>
<li><strong>Q 0.4</strong>: <a class="normal" href="#remarks">What should I put in the remarks.md file of my submission?</a></li>
<li><strong>Q 0.5</strong>: <a class="normal" href="#try_scripts">What should I do with the <code>try.sh</code> and <code>try.alt.sh</code> scripts?</a></li>
<li><strong>Q 0.6</strong>: <a class="normal" href="#file_perms">What permissions may my files be and what if I need different permissions?</a></li>
</ul>
<h2 id="entering-the-ioccc-more-help-and-details">1. <a href="#submitting_help">Entering the IOCCC: more help and details</a></h2>
<ul>
@@ -467,7 +468,7 @@
</ul>
<h2 id="the-mkiocccentry-toolkit-finer-details">3. <a href="#mkiocccentry_details">The mkiocccentry toolkit: finer details</a></h2>
<ul>
<li><strong>Q 3.0</strong>: <a class="normal" href="#mkiocccentry_checks">What sort of checks does the mkiocccentry tool perform?</a></li>
<li><strong>Q 3.0</strong>: <a class="normal" href="#mkiocccentry_process">What is the <code>mkiocccentry(1)</code> process and what sort of checks does it perform?</a></li>
<li><strong>Q 3.1</strong>: <a class="normal" href="#txzchk">How can I validate my submission tarball?</a></li>
<li><strong>Q 3.2</strong>: <a class="normal" href="#fnamchk">What is the <code>fnamchk</code> tool?</a></li>
<li><strong>Q 3.3</strong>: <a class="normal" href="#chkentry">How can I validate my <code>.auth.json</code> and/or <code>.info.json</code> files?</a></li>
@@ -628,10 +629,12 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>
as <code>MAX_FILE_COUNT</code>) and other information about your submission,
information about the author (or authors), and then it runs a lot of tests before (if
all is OK) forming your tarball. After this is done it will additionally run the
<code>txzchk(1)</code> tool (which runs the <code>fnamchk(1)</code> tool) on the submission tarball.
The tool <code>chkentry(1)</code> will also be run, before creating the tarball. See the
information about the author (or authors), and then it runs a lot of tests.</p>
<p>If everything is OK, it will write the required <code>.auth.json</code> and <code>.info.json</code>
files, checking each with <code>chkentry(1)</code> and then, if all is OK, it will create
the tarball. After the tarball is formed, it will run <code>txzchk(1)</code> on it, which
runs <code>fnamchk(1)</code>. If all is OK, your submission tarball should be good to go.</p>
<p>Please see
FAQ on “<a href="#txzchk">txzchk</a>”,
the
FAQ on “<a href="#fnamchk">fnamchk</a>”
@@ -694,6 +697,16 @@ directory</strong> will be created, with the name based on your IOCCC registrati
username, which is <strong>in the form of a UUID</strong>, and submission number; see the
<a href="next/rules.html">rules</a> for more details on this, and in particular <a href="next/rules.html#rule17">Rule
17</a>.</p>
<p><strong>IMPORTANT NOTE</strong>: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
are required like <code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fnamchk(1)</code>. 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 <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).</p>
<p>If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> (based on your submit ID and
slot number) already exists, you will have to
move it, remove it or otherwise specify a different work directory (<strong>NOT</strong> the
@@ -701,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>
@@ -797,27 +810,36 @@ the one linked to above.</p>
</div>
</div>
</div>
<p>First, <strong>PLEASE</strong> read the <a href="markdown.html">IOCCC markdown guidelines</a>.</p>
<p><strong>PLEASE</strong> look at the template remarks.md to give you a better idea of how
it should be formed, as it has some instructions you should follow:</p>
<ul>
<li><a href="https://github.com/ioccc-src/winner/blob/master/next/remarks.example.md">view template remarks.md</a></li>
<li><a href="next/remarks.example.md">remarks.md template</a></li>
</ul>
<p><strong>PLEASE</strong> pay especial attention to the instructions, including the <a href="markdown.html">IOCCC
markdown guidelines</a>. You will observe that it links back to this
FAQ as to what you should or should not say.</p>
<p>Next, while you may put in as much or as little as you wish into your entry’s
<code>remarks.md</code> file, we do have few important suggestions:</p>
<p>We recommend that you explain how to use your entry. Explain the
<p>We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.</p>
<p>We highly recommend that you explain why you think your entry is
<p>We highly recommend that you explain why you think your submission is
well obfuscated.</p>
<p>For those submissions that win the IOCCC, we often use much of text from the
<code>remarks.md</code> file in the <em>Author’s remarks</em> section of the <code>index.html</code> file.
For this reason, a well written <code>remarks.md</code> file is considered a plus.</p>
<p>While not required, consider adding bit of humor to your <code>remarks.md</code>
as most people who are not humor impaired, as well as the IOCCC judges
appreciate the opportunity for a fun read as well as a chuckle or two.</p>
as most people who are not humor impaired, as well as the IOCCC judges (who
might or might not be humour impaired :-) ), appreciate the opportunity for a
fun read as well as a chuckle or two.</p>
<h4 id="what-helps">What helps:</h4>
<ul>
<li>explaining what your entry does</li>
<li>how to entice it to do what it is supposed to do</li>
<li>what obfuscations are used</li>
<li>what are the limitations of your entry in respect of portability and/or input data</li>
<li>how it works (if you are really condescending)</li>
<li>explaining what your entry does.</li>
<li>how to entice it to do what it is supposed to do.</li>
<li>what obfuscations are used.</li>
<li>what are the limitations of your entry in respect of portability and/or input data.</li>
<li>how it works (if you are really condescending).</li>
</ul>
<h4 id="what-does-not-help">What does not help:</h4>
<ul>
@@ -829,11 +851,13 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
<a href="next/guidelines.html">guidelines</a> <strong>AND</strong> <a href="next/rules.html">rules</a> if this is not clear!</li>
<li>leaving the remark section empty.</li>
<li>leaving the remark section empty (which would also indicate that you did not
use <code>mkiocccentry(1)</code>, as it requires it to not be of size 0, though if you only
include whitespace you would still be violating <a href="next/rules.html#rule17">Rule 17</a>).</li>
</ul>
<p>Jump to: <a href="#">top</a></p>
<div id="try_scripts">
<h3 id="q-0.5-what-should-i-do-with-the-try.sh-and-try.alt.sh-scripts">Q 0.5 What should I do with the <code>try.sh</code> and <code>try.alt.sh</code> scripts?</h3>
<h3 id="q-0.5-what-should-i-do-with-the-try.sh-and-try.alt.sh-scripts">Q 0.5: What should I do with the <code>try.sh</code> and <code>try.alt.sh</code> scripts?</h3>
</div>
<p>If your submission has more than one use, or if you have interesting ways to
invoke your program, perhaps using other commonly installed tools (or tools
@@ -858,6 +882,22 @@ but we do enjoy interesting and creative uses of submissions.</p>
example Makefile that you modify for your submission. See the
FAQ on “<a href="#makefile">submission Makefiles</a>.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="file_perms">
<h3 id="q-0.6-what-permissions-may-my-files-be-and-what-if-i-need-different-permissions">Q 0.6: What permissions may my files be and what if I need different permissions?</h3>
</div>
<p>As <a href="#rule17">Rule 17</a> states, files in your submission tarball <strong>MUST</strong> be
specific permissions. In particular: directories <strong>MUST</strong> be <code>drwxr-xr-x</code> (i.e.
<code>0755</code>), the optional files, <code>try.sh</code> or <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>).</p>
<p>If you need a file to be executable, say a script, then make sure you do so in
the appropriate place in your Makefile. See the
FAQ on “<a href="#makefile">submission Makefile</a>”
for more details.</p>
<p>Do remember that if your submission requires different filenames, then you
<strong>MUST</strong> make a <strong>COPY</strong> of them in your <code>Makefile</code>. See also <a href="next/rules.html#rule11">Rule
11</a>.</p>
Jump to: <a href="#">top</a>
<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">
<div id="submitting_help">
@@ -1349,34 +1389,189 @@ entries that do not win on their web page for everyone to see.</p>
<h2 id="section-3-the-mkiocccentry-toolkit-finer-details">Section 3: The mkiocccentry toolkit: finer details</h2>
</div>
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 id="mkiocccentry_process">
<h3 id="q-3.0-what-is-the-mkiocccentry1-process-and-what-sort-of-checks-does-it-perform">Q 3.0: What is the <code>mkiocccentry(1)</code> process and what sort of checks does it perform?</h3>
</div>
<p><code>mkiocccentry(1)</code> will check and warn about the following conditions:</p>
<p>In full, the <code>mkiocccentry(1)</code> tool performs the following steps:</p>
<ol start="0" type="1">
<li>Ask the user for a submission ID (see the <a href="next/register.html">how to register</a>
for more details on how to obtain this and <a href="next/rules.html#rule17">Rule 17</a> for
the importance of this).
<ul>
<li>If this is an invalid UUID (malformed), you will be asked to correct it
until it is.</li>
</ul></li>
<li>Ask the user for the submission slot (the submission number; see <a href="next/register.html">how to
register</a> and <a href="next/rules.html#rule17">Rule 17</a> for more details).
<ul>
<li>If this is out of range (see <code>MAX_SUBMIT_SLOT</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>)
and you will be asked to correct it until it is.</li>
</ul></li>
<li>Make the submission directory under <code>topdir</code> in the form of
<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code> (the timestamp is calculated by
<code>mkiocccentry(1)</code> so you do not have to worry about this).
<ul>
<li>If this directory already exists it is an error.</li>
</ul></li>
<li>Change to the <code>topdir</code>.</li>
<li>Traverse the directory, creating lists of ignored/forbidden
files/directories/symlinks as well as a list directories to make and a list of
files to copy to the submission directory (and if (sub)directories are found
with files, copy those files to their respective directory). Note the following:
<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 there are too many extra directories (total count not including the
submission directory itself, unrelated to <code>MAX_PATH_DEPTH</code> above) it is an
error (see <code>MAX_EXTRA_DIR_COUNT</code> in
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>If the max path length is &lt;= 0 it is an error (and a bug).</li>
<li>If the max depth is &lt;= 0 it is an error (and a bug).</li>
<li>If the max filename length is &lt;= 0 it is an error (and a bug).</li>
<li>If a path is NULL it is an error.</li>
<li>If a path is an empty string it is an error.</li>
<li>If the path length (i.e. <code>strlen(path)</code> where path starts after the
initial <code>./</code> of the path in the <code>topdir</code>) is 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 (last component of the path) 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 filename or directory name is not a sane relative path, not allowed
or will not be added for some other reason, it will be added to a relevant list to show to
the user later, to let them know it will not be added to the submission. By <code>relative</code> we mean it
must not start with <code>/</code> (which shouldn’t happen even if you give an absolute
path) and by <code>sane</code> we mean that each component must match the regexp: <code>^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$</code>.</li>
<li>If a directory is unreadable it is an error.</li>
<li>If a directory causes a cycle in the tree it is an error.</li>
<li>If <code>stat(2)</code> on the path fails it is an error.</li>
<li>If <code>prog.c</code>, <code>Makefile</code> or <code>remarks.md</code> is/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>
<li>Symlinks are not allowed but it is not an error (they will be added to a
list and ignored).</li>
<li>If any file type other than a regular file, a directory or a symlink is
encountered it is an error.</li>
<li>If there is an unknown error it is an error :-)</li>
</ul></li>
<li>Show each list to the user, asking if this is okay. The lists include:
<ul>
<li>Ignored directories (those like <code>.git</code>, <code>CVS</code>, <code>RCCS</code> and <code>.svn</code>).</li>
<li>Unsafe directory names that will not be added (i.e. those that are not
POSIX plus + safe chars only; see above step (4)). This includes directories
starting with a <code>.</code>.</li>
<li>Forbidden files such as <code>index.html</code>, <code>README.md</code>, <code>prog</code>, <code>prog.alt</code>.</li>
<li>Unsafe filenames that will not be added (i.e. those that are not POSIX
plus + safe chars only; see above step (4)). This includes files starting
with <code>.</code>.</li>
<li>Symlinks found (these are not allowed).</li>
<li>Directories to be made.</li>
<li>Required files (<code>prog.c</code>, <code>Makefile</code> and <code>remarks.md</code>) to be copied.</li>
<li>Non-required files to be copied.</li>
<li>The user is asked to verify each list, including the lists of directories
and files to be made/copied, and if the user says it is not OK the program will abort.</li>
</ul></li>
<li>Make any directories if necessary (under
<code>workdir/submit.USERNAME-SLOT.TIMESTAMP</code> i.e. the submission directory).
<ul>
<li>Directories <strong>MUST</strong> be and are made with mode <code>0755</code>.</li>
<li>If any directory is not this mode <code>txzchk(1)</code> will flag it.</li>
</ul></li>
<li>The non-ignored files are copied to their respective directories under the
submission directory.
<ul>
<li><code>try.sh</code> and <code>try.alt.sh</code> <strong>MUST</strong> be and are copied as mode <code>0555</code>.</li>
<li>All other files <strong>MUST</strong> be and are copied as mode <code>0444</code>.</li>
<li>Anything else will be flagged by <code>txzchk(1)</code>.</li>
</ul></li>
<li><code>cd submit.USERNAME-SLOT.TIMESTAMP</code> (i.e. switch to submission directory).</li>
<li><code>make -f Makefile clobber</code>.
<ul>
<li>If this fails it is not an error but you are warned about it (it is an error only if the <code>Makefile</code>
does not exist); even so, see <a href="next/rules.html#rule20">Rule 20</a>.</li>
</ul></li>
<li>Traverse the new tree from <code>.</code> with additional steps from (4).
<ul>
<li>If any file has an ignored directory name in it, it is an error.</li>
<li>If a symlink is found it is an error.</li>
<li>If any file type other than a directory or regular file exists it is an
error.</li>
<li>If a forbidden filename exists it is an error.</li>
<li>If any file or directory starts with <code>/</code> or is not POSIX plus + safe chars
only (see (4) above) 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 (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, and having a <code>remarks.md</code> that is not size 0
but has no content is violating <a href="next/rules.html#rule17">Rule 17</a> and <a href="next/rules.html#rule19">Rule
19</a>.</li>
<li>If any other error condition from step (4) occurs it is also an error.</li>
</ul></li>
<li>Report on any directories that were made and files that were copied in (7)
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>Ask the user for a submission title.</li>
<li>Ask the user for a one line abstract of the submission.</li>
<li>Ask the user for the number of authors and for each author ask a variety of
questions (see below for more information on what kind of questions).</li>
<li>Show the output of <code>ls -lakR .</code>, asking the user to confirm that the listing
is okay.</li>
<li>Create <code>.info.json</code> and run <code>chkentry(1)</code> on it.
<ul>
<li>If <code>chkentry(1)</code> fails to validate the file make sure that you have
obtained and compiled the latest version of all the tools and you either are
in the repo’s directory, you pass the options to give the path to the tools
or you have installed the latest tools!</li>
</ul></li>
<li>Create <code>.auth.json</code> and run <code>chkentry(1)</code> on it.
<ul>
<li>If <code>chkentry(1)</code> fails to validate the file make sure that you have
obtained and compiled the latest version of all the tools and you either are
in the repo’s directory, you pass the options to give the path to the tools
or you have installed the latest tools!</li>
</ul></li>
<li>Create the tarball.</li>
<li>Run <code>txzchk(1)</code> on the tarball.</li>
</ol>
<p>If any of the steps fail or if the user says something is not okay, it aborts.
Some of the other checks that are made:</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
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<li>If <code>prog.c</code> is empty.</li>
<li>If <code>prog.c</code> has any high bit char (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<li>If <code>prog.c</code> has any NUL char (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<li>If <code>prog.c</code> is empty (see <a href="next/rules.html#rule1">Rule 1</a> and the
<a href="next/guidelines.html">Guidelines</a>).</li>
<li>If <code>prog.c</code> has any NUL (<code>\0</code>) char (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c">rule_count.c</a>).</li>
<li>If <code>prog.c</code> has any unknown or invalid trigraph (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c">rule_count.c</a>).</li>
<li>If <code>prog.c</code> triggers a word buffer overflow (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c">rule_count.c</a>).</li>
<li>If <code>prog.c</code> triggers an <code>ungetc(3)</code> error (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>).</li>
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c">rule_count.c</a>).</li>
<li>If the first rule in the <code>Makefile</code> is not <code>all</code>.</li>
<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>Conditions that one must correct, and which <code>mkiocccentry(1)</code> will prompt until
<p>Conditions that one <strong>MUST</strong> correct, and which <code>mkiocccentry(1)</code> will prompt until
they are correct, are:</p>
<ul>
<li>Your <em>contest ID</em> is invalidly formed.</li>
<li>Your <em>submit slot</em> is &lt; 0 or &gt; <code>MAX_SUBMIT_SLOT</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>Your <em>title</em> is not in the range of 1 through <code>MAX_TITLE_LEN</code> chars (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>Your <em>title</em> does not match the regexp <code>^[0-9a-z][0-9a-z._+-]*$</code>.</li>
@@ -1387,8 +1582,7 @@ they are correct, are:</p>
<li>An author <em>name</em> is not 1 through <code>MAX_NAME_LEN</code> chars (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>Duplicate author <em>name</em>.</li>
<li><em>Country code</em> is invalid (not ISO 3166-1 2 character
codes).</li>
<li><em>Country code</em> is invalid (i.e. it is not a ISO 3166-1 2 character code).</li>
<li>An <em>email</em>, if provided, is not in the format of <code>x@y</code> or
if <code>x</code> or <code>y</code> contain a <code>@</code>, are empty or if the total length is longer than
<code>MAX_EMAIL_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
@@ -1398,18 +1592,20 @@ or <code>https://</code> or is longer than <code>MAX_URL_LEN</code> chars (see
or does not have anything after the <code>http://</code> or <code>https://</code>.</li>
<li>A <em>mastodon handle</em>, if provided, is not in the form of
<code>@user@site</code> (i.e. starts with an <code>@</code>, has text following it and then another
<code>@</code> followed by more text and has no other <code>@</code>) or is longer than <code>MAX_MASTODON_LEN</code> (see
<code>@</code> followed by more text and has no other <code>@</code>), or if it is longer than <code>MAX_MASTODON_LEN</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>A <em>GitHub account</em>, if provided, does not start with an <code>@</code>,
has more than one <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (see
has more than one <code>@</code>, does not have any text after the <code>@</code> or is longer than <code>MAX_GITHUB_LEN</code> (see
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<li>An <em>affiliation</em>, if provided, is longer than
<code>MAX_AFFILIATION_LEN</code> (see <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>).</li>
<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>
<p>The program does confirm that the information for each author is correct,
allowing you to correct the information without having to start the program
over.</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>
@@ -1428,8 +1624,12 @@ FAQ on “<a href="#fnamchk">fnamchk</a>”
for more details on the tools that <code>mkiocccentry</code> either executes directly or
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
FAQ on “<a href="#mkiocccentry_test">how to test everything at once without having to answer
questions</a>”.</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#rule1">Rule 1</a>, <a href="next/rules.html#rule2">Rule 2</a>, <a href="next/rules.html#rule17">Rule
17</a>, <a href="next/rules.html#rule19">Rule 19</a> and <a href="next/rules.html#rule20">Rule 20</a>).</p>
<p>Jump to: <a href="#">top</a></p>
<div id="txzchk">
<div id="tarball">
faq.md
+234 -43
View File
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
This is FAQ version **28.2.2 2025-01-30**.
This is FAQ version **28.2.8 2025-02-10**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -14,6 +14,7 @@ This is FAQ version **28.2.2 2025-01-30**.
- **Q 0.3**: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a>
- **Q 0.4**: <a class="normal" href="#remarks">What should I put in the remarks.md file of my submission?</a>
- **Q 0.5**: <a class="normal" href="#try_scripts">What should I do with the `try.sh` and `try.alt.sh` scripts?</a>
- **Q 0.6**: <a class="normal" href="#file_perms">What permissions may my files be and what if I need different permissions?</a>
## 1. [Entering the IOCCC: more help and details](#submitting_help)
@@ -41,7 +42,7 @@ This is FAQ version **28.2.2 2025-01-30**.
## 3. [The mkiocccentry toolkit: finer details](#mkiocccentry_details)
- **Q 3.0**: <a class="normal" href="#mkiocccentry_checks">What sort of checks does the mkiocccentry tool perform?</a>
- **Q 3.0**: <a class="normal" href="#mkiocccentry_process">What is the `mkiocccentry(1)` process and what sort of checks does it perform?</a>
- **Q 3.1**: <a class="normal" href="#txzchk">How can I validate my submission tarball?</a>
- **Q 3.2**: <a class="normal" href="#fnamchk">What is the `fnamchk` tool?</a>
- **Q 3.3**: <a class="normal" href="#chkentry">How can I validate my `.auth.json` and/or `.info.json` files?</a>
@@ -217,10 +218,14 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
as `MAX_FILE_COUNT`) and other information about your submission,
information about the author (or authors), and then it runs a lot of tests before (if
all is OK) forming your tarball. After this is done it will additionally run the
`txzchk(1)` tool (which runs the `fnamchk(1)` tool) on the submission tarball.
The tool `chkentry(1)` will also be run, before creating the tarball. See the
information about the author (or authors), and then it runs a lot of tests.
If everything is OK, it will write the required `.auth.json` and `.info.json`
files, checking each with `chkentry(1)` and then, if all is OK, it will create
the tarball. After the tarball is formed, it will run `txzchk(1)` on it, which
runs `fnamchk(1)`. If all is OK, your submission tarball should be good to go.
Please see
FAQ on "[txzchk](#txzchk)",
the
FAQ on "[fnamchk](#fnamchk)"
@@ -314,6 +319,17 @@ username, which is **in the form of a UUID**, and submission number; see the
[rules](next/rules.html) for more details on this, and in particular [Rule
17](next/rules.html#rule17).
**IMPORTANT NOTE**: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
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 via `sudo` or as root).
If the **_subdirectory_ in the _work directory_** (based on your submit ID and
slot number) already exists, you will have to
move it, remove it or otherwise specify a different work directory (**NOT** the
@@ -323,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)
@@ -431,16 +446,24 @@ Jump to: [top](#)
</div>
</div>
First, **PLEASE** read the [IOCCC markdown guidelines](markdown.html).
**PLEASE** look at the template remarks.md to give you a better idea of how
it should be formed, as it has some instructions you should follow:
- [view template remarks.md](%%REPO_URL%%/next/remarks.example.md)
- [remarks.md template](next/remarks.example.md)
**PLEASE** pay especial attention to the instructions, including the [IOCCC
markdown guidelines](markdown.html). You will observe that it links back to this
FAQ as to what you should or should not say.
Next, while you may put in as much or as little as you wish into your entry's
`remarks.md` file, we do have few important suggestions:
We recommend that you explain how to use your entry. Explain the
We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.
We highly recommend that you explain why you think your entry is
We highly recommend that you explain why you think your submission is
well obfuscated.
For those submissions that win the IOCCC, we often use much of text from the
@@ -448,17 +471,18 @@ For those submissions that win the IOCCC, we often use much of text from the
For this reason, a well written `remarks.md` file is considered a plus.
While not required, consider adding bit of humor to your `remarks.md`
as most people who are not humor impaired, as well as the IOCCC judges
appreciate the opportunity for a fun read as well as a chuckle or two.
as most people who are not humor impaired, as well as the IOCCC judges (who
might or might not be humour impaired :-) ), appreciate the opportunity for a
fun read as well as a chuckle or two.
#### What helps:
- explaining what your entry does
- how to entice it to do what it is supposed to do
- what obfuscations are used
- what are the limitations of your entry in respect of portability and/or input data
- how it works (if you are really condescending)
- explaining what your entry does.
- how to entice it to do what it is supposed to do.
- what obfuscations are used.
- what are the limitations of your entry in respect of portability and/or input data.
- how it works (if you are really condescending).
#### What does not help:
@@ -471,13 +495,15 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
[guidelines](next/guidelines.html) **AND** [rules](next/rules.html) if this is not clear!
- leaving the remark section empty.
- leaving the remark section empty (which would also indicate that you did not
use `mkiocccentry(1)`, as it requires it to not be of size 0, though if you only
include whitespace you would still be violating [Rule 17](next/rules.html#rule17)).
Jump to: [top](#)
<div id="try_scripts">
### Q 0.5 What should I do with the `try.sh` and `try.alt.sh` scripts?
### Q 0.5: What should I do with the `try.sh` and `try.alt.sh` scripts?
</div>
If your submission has more than one use, or if you have interesting ways to
@@ -510,6 +536,30 @@ FAQ on "[submission Makefiles](#makefile).
Jump to: [top](#)
<div id="file_perms">
### Q 0.6: What permissions may my files be and what if I need different permissions?
</div>
As [Rule 17](#rule17) states, files in your submission tarball **MUST** be
specific permissions. 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 you need a file to be executable, say a script, then make sure you do so in
the appropriate place in your Makefile. See the
FAQ on "[submission Makefile](#makefile)"
for more details.
Do remember that if your submission requires different filenames, then you
**MUST** make a **COPY** of them in your `Makefile`. See also [Rule
11](next/rules.html#rule11).
Jump to: [top](#)
<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">
@@ -1158,35 +1208,169 @@ Jump to: [top](#)
Jump to: [top](#)
<div id="mkiocccentry_checks">
### Q 3.0: What sort of checks does the mkiocccentry tool perform?
<div id="mkiocccentry_process">
### Q 3.0: What is the `mkiocccentry(1)` process and what sort of checks does it perform?
</div>
`mkiocccentry(1)` will check and warn about the following conditions:
In full, the `mkiocccentry(1)` tool performs the following steps:
0. Ask the user for a submission ID (see the [how to register](next/register.html)
for more details on how to obtain this and [Rule 17](next/rules.html#rule17) for
the importance of this).
* If this is an invalid UUID (malformed), you will be asked to correct it
until it is.
1. Ask the user for the submission slot (the submission number; see [how to
register](next/register.html) and [Rule 17](next/rules.html#rule17) for more details).
* If this is out of range (see `MAX_SUBMIT_SLOT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
and you will be asked to correct it until it is.
2. Make the submission directory under `topdir` in the form of
`workdir/submit.USERNAME-SLOT.TIMESTAMP` (the timestamp is calculated by
`mkiocccentry(1)` so you do not have to worry about this).
* If this directory already exists it is an error.
3. Change to the `topdir`.
4. Traverse the directory, creating lists of ignored/forbidden
files/directories/symlinks as well as a list directories to make and a list of
files to copy to the submission directory (and if (sub)directories are found
with files, copy those files to their respective directory). Note the following:
* 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 there are too many extra directories (total count not including the
submission directory itself, unrelated to `MAX_PATH_DEPTH` above) it is an
error (see `MAX_EXTRA_DIR_COUNT` in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
* If the max path length is <= 0 it is an error (and a bug).
* If the max depth is <= 0 it is an error (and a bug).
* If the max filename length is <= 0 it is an error (and a bug).
* If a path is NULL it is an error.
* If a path is an empty string it is an error.
* If the path length (i.e. `strlen(path)` where path starts after the
initial `./` of the path in the `topdir`) is 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 (last component of the path) 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 filename or directory name is not a sane relative path, not allowed
or will not be added for some other reason, it will be added to a relevant list to show to
the user later, to let them know it will not be added to the submission. By `relative` we mean it
must not start with `/` (which shouldn't happen even if you give an absolute
path) and by `sane` we mean that each component must match the regexp: `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$`.
* If a directory is unreadable it is an error.
* If a directory causes a cycle in the tree it is an error.
* If `stat(2)` on the path fails it is an error.
* If `prog.c`, `Makefile` or `remarks.md` is/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)).
* Symlinks are not allowed but it is not an error (they will be added to a
list and ignored).
* If any file type other than a regular file, a directory or a symlink is
encountered it is an error.
* If there is an unknown error it is an error :-)
5. Show each list to the user, asking if this is okay. The lists include:
* Ignored directories (those like `.git`, `CVS`, `RCCS` and `.svn`).
* Unsafe directory names that will not be added (i.e. those that are not
POSIX plus + safe chars only; see above step (4)). This includes directories
starting with a `.`.
* Forbidden files such as `index.html`, `README.md`, `prog`, `prog.alt`.
* Unsafe filenames that will not be added (i.e. those that are not POSIX
plus + safe chars only; see above step (4)). This includes files starting
with `.`.
* Symlinks found (these are not allowed).
* Directories to be made.
* Required files (`prog.c`, `Makefile` and `remarks.md`) to be copied.
* Non-required files to be copied.
* The user is asked to verify each list, including the lists of directories
and files to be made/copied, and if the user says it is not OK the program will abort.
6. Make any directories if necessary (under
`workdir/submit.USERNAME-SLOT.TIMESTAMP` i.e. the submission directory).
* Directories **MUST** be and are made with mode `0755`.
* If any directory is not this mode `txzchk(1)` will flag it.
7. The non-ignored files are copied to their respective directories under the
submission directory.
* `try.sh` and `try.alt.sh` **MUST** be and are copied as mode `0555`.
* All other files **MUST** be and are copied as mode `0444`.
* Anything else will be flagged by `txzchk(1)`.
8. `cd submit.USERNAME-SLOT.TIMESTAMP` (i.e. switch to submission directory).
9. `make -f Makefile clobber`.
* If this fails it is not an error but you are warned about it (it is an error only if the `Makefile`
does not exist); even so, see [Rule 20](next/rules.html#rule20).
10. Traverse the new tree from `.` with additional steps from (4).
* If any file has an ignored directory name in it, it is an error.
* If a symlink is found it is an error.
* If any file type other than a directory or regular file exists it is an
error.
* If a forbidden filename exists it is an error.
* If any file or directory starts with `/` or is not POSIX plus + safe chars
only (see (4) above) it is an error.
* If the depth is too deep 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, and having a `remarks.md` that is not size 0
but has no content is violating [Rule 17](next/rules.html#rule17) and [Rule
19](next/rules.html#rule19).
* If any other error condition from step (4) occurs it is also an error.
11. Report on any directories that were made and files that were copied in (7)
but are now gone: asking the user to verify.
12. Present the list of non-dot files that remain and ask the user to confirm.
13. Ask the user for a submission title.
14. Ask the user for a one line abstract of the submission.
15. Ask the user for the number of authors and for each author ask a variety of
questions (see below for more information on what kind of questions).
16. Show the output of `ls -lakR .`, asking the user to confirm that the listing
is okay.
17. Create `.info.json` and run `chkentry(1)` on it.
* If `chkentry(1)` fails to validate the file make sure that you have
obtained and compiled the latest version of all the tools and you either are
in the repo's directory, you pass the options to give the path to the tools
or you have installed the latest tools!
18. Create `.auth.json` and run `chkentry(1)` on it.
* If `chkentry(1)` fails to validate the file make sure that you have
obtained and compiled the latest version of all the tools and you either are
in the repo's directory, you pass the options to give the path to the tools
or you have installed the latest tools!
19. Create the tarball.
20. Run `txzchk(1)` on the tarball.
If any of the steps fail or if the user says something is not okay, it aborts.
Some of the other checks that are made:
- 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
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
- If `prog.c` is empty.
- If `prog.c` has any high bit char (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
- If `prog.c` has any NUL char (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
- If `prog.c` is empty (see [Rule 1](next/rules.html#rule1) and the
[Guidelines](next/guidelines.html)).
- If `prog.c` has any NUL (`\0`) char (see
[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` has any unknown or invalid trigraph (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers a word buffer overflow (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers an `ungetc(3)` error (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If the first rule in the `Makefile` is not `all`.
- 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.
Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
Conditions that one **MUST** correct, and which `mkiocccentry(1)` will prompt until
they are correct, are:
- Your _contest ID_ is invalidly formed.
- Your _submit slot_ is < 0 or > `MAX_SUBMIT_SLOT` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.
@@ -1197,8 +1381,7 @@ they are correct, are:
- An author _name_ is not 1 through `MAX_NAME_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Duplicate author _name_.
- _Country code_ is invalid (not ISO 3166-1 2 character
codes).
- _Country code_ is invalid (i.e. it is not a ISO 3166-1 2 character code).
- An _email_, if provided, is not in the format of `x@y` or
if `x` or `y` contain a `@`, are empty or if the total length is longer than
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1208,17 +1391,20 @@ or `https://` or is longer than `MAX_URL_LEN` chars (see
or does not have anything after the `http://` or `https://`.
- A _mastodon handle_, if provided, is not in the form of
`@user@site` (i.e. starts with an `@`, has text following it and then another
`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
`@` followed by more text and has no other `@`), or if it is longer than `MAX_MASTODON_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- A _GitHub account_, if provided, does not start with an `@`,
has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
has more than one `@`, does not have any text after the `@` or is longer than `MAX_GITHUB_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- An _affiliation_, if provided, is longer than
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- 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.
The program does confirm that the information for each author is correct,
allowing you to correct the information without having to start the program
over.
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
@@ -1240,8 +1426,13 @@ for more details on the tools that `mkiocccentry` either executes directly or
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
See also the
FAQ on "[how to test everything at once without having to answer
questions](#mkiocccentry_test)".
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
(and in particular [Rule 17](next/rules.html#rule17)).
(especially [Rule 1](next/rules.html#rule1), [Rule 2](next/rules.html#rule2), [Rule
17](next/rules.html#rule17), [Rule 19](next/rules.html#rule19) and [Rule 20](next/rules.html#rule20)).
Jump to: [top](#)
markdown.html
+25 -5
View File
@@ -431,13 +431,13 @@
<h2 id="ioccc-markdown-guidelines-version">IOCCC Markdown guidelines version</h2>
</div>
<p class="leftbar">
These <a href="markdown.html">IOCCC markdown guidelines</a> are version <strong>28.1 2024-12-27</strong>.
These <a href="markdown.html">IOCCC markdown guidelines</a> are version <strong>28.1 2025-02-02</strong>.
</p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="next/rules.html">IOCCC rules</a> and <a href="next/guidelines.html">IOCCC
guidelines</a>.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="markdown">
<h2 id="ioccc-markdown-guidelines">IOCCC Markdown guidelines</h2>
<div id="introduction">
<h2 id="ioccc-markdown-guidelines-introduction">IOCCC Markdown Guidelines Introduction</h2>
</div>
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
For example, when submitting to the IOCCC
@@ -454,9 +454,29 @@ FAQ on “<a href="faq.html#remarks_md">remarks.md submission file</a>”.</p>
<p>Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.</p>
<p>In particular there are things we ask people to please <strong>NOT</strong> use in
markdown files for the IOCCC:</p>
<p>Jump to: <a href="#">top</a></p>
<div id="sections">
<h2 id="please-do-start-remarks.md-sections-at-level-3-increasing-for-subsections-up-to-6">Please DO start <code>remarks.md</code> sections at level 3 (<code>###</code>), increasing for subsections up to 6 (<code>######</code>)</h2>
</div>
<p>IF (it is not required) you do use sections in your <code>remarks.md</code> file (this does
not apply to other markdown files), <strong>PLEASE</strong> start at level three:</p>
<pre><code> # Foo &lt;=== no thank you
## Foo &lt;=== no thank you</code></pre>
<p>Instead, start sections with 3 <code>#</code>s:</p>
<pre><code> ### Section 0</code></pre>
<p>For each subsection of the current section, add another <code>#</code>, up to 6, going back
to 3 for new sections. For instance:</p>
<pre><code> ### Section 0
...
#### First subsection of section 0
...
##### Second subsection of section 0
...
###### Third subsection of section 0
...
### Section 1
...
Etc.</code></pre>
<div id="name">
<div id="anchor-name">
<h2 id="please-do-not-use-the-name-attributes-in-html-a...a-hyperlink-elements">Please do NOT use the <code>name</code> attributes in HTML <code>&lt;a&gt;...&lt;/a&gt;</code> hyperlink elements</h2>
markdown.md
+41 -6
View File
@@ -7,7 +7,7 @@
</div>
<p class="leftbar">
These [IOCCC markdown guidelines](markdown.html) are version **28.1 2024-12-27**.
These [IOCCC markdown guidelines](markdown.html) are version **28.1 2025-02-02**.
</p>
**IMPORTANT**: Be sure to read the [IOCCC rules](next/rules.html) and [IOCCC
@@ -16,8 +16,8 @@ guidelines](next/guidelines.html).
Jump to: [top](#)
<div id="markdown">
## IOCCC Markdown guidelines
<div id="introduction">
## IOCCC Markdown Guidelines Introduction
</div>
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
@@ -38,11 +38,46 @@ Nevertheless, the IOCCC does have certain practices that we ask authors to follo
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.
In particular there are things we ask people to please **NOT** use in
markdown files for the IOCCC:
Jump to: [top](#)
<div id="sections">
## Please DO start `remarks.md` sections at level 3 (`###`), increasing for subsections up to 6 (`######`)
</div>
IF (it is not required) you do use sections in your `remarks.md` file (this does
not apply to other markdown files), **PLEASE** start at level three:
``` <!---markdown-->
# Foo <=== no thank you
## Foo <=== no thank you
```
Instead, start sections with 3 `#`s:
``` <!---markdown-->
### Section 0
```
For each subsection of the current section, add another `#`, up to 6, going back
to 3 for new sections. For instance:
``` <!---markdown-->
### Section 0
...
#### First subsection of section 0
...
##### Second subsection of section 0
...
###### Third subsection of section 0
...
### Section 1
...
Etc.
```
<div id="name">
<div id="anchor-name">
## Please do NOT use the `name` attributes in HTML `<a>...</a>` hyperlink elements
next/Makefile.example
+5 -1
View File
@@ -153,12 +153,16 @@ ALT_TARGET=
#
DATA=
#################
# build the entry
#################
all: data ${TARGET}
# NOTE: only try.sh and try.alt.sh scripts will be made executable in
# the tarball so if you need any scripts that are executable, make sure
# to use ${CHMOD} +x on them like:
#
# ${CHMOD} +x foo.sh
.PHONY: all data try clean clobber install
next/guidelines.html
+79 -63
View File
@@ -461,7 +461,7 @@ 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.35 2025-01-30</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.36 2025-02-03</strong>.
</p>
<p class="leftbar">
The <a href="guidelines.md" download="guidelines.md">markdown form of these guidelines</a>
@@ -609,12 +609,28 @@ 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
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
are required like <code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fnamchk(1)</code>. 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 <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).
</p>
<p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> has been <strong>significantly modified</strong>
to account for the new <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> tools.
Thus, you are <strong>STRONGLY</strong> advised to use the <code>mkiocccentry(1)</code> tool
as found in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
to form the file to upload to the <a href="https://submit.ioccc.org">submit server</a>. Not
doing so puts you at a very big risk of violating <a href="rules.html#rule17">Rule 17</a>.
using <code>mkiocccentry(1)</code> the <a href="https://submit.ioccc.org">submit server</a>. Uploading
a tarball not formed by <code>mkiocccentry(1)</code> puts you at a very big risk of
violating <a href="rules.html#rule17">Rule 17</a>, especially as <code>mkiocccentry(1)</code> does a
great number of things that are required, and it also runs many checks, and if
any of those checks fail, you are at a very great risk of having your submission
rejected for violating <a href="rules.html#rule17">Rule 17</a>.
</p>
<p class="leftbar">
See the
@@ -816,66 +832,6 @@ specific terminal brand. Programs that work in a standard xterm
are considered more portable.
</p>
<p>Jump to: <a href="#">top</a></p>
<div id="extra-files">
<h1 id="including-optional-and-extra-files">Including optional and extra files</h1>
</div>
<p class="leftbar">
The maximum total number of files that may be submitted has changed to 39 files.
However, of those files, 5 are mandatory (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code> and
the two JSON files generated by <code>mkiocccentry(1)</code>, <code>.info.json</code> and
<code>.auth.json</code>).
</p>
<p class="leftbar">
Additionally, three of the files, if included, <strong>MUST</strong> be
specific file(name)s and in the top level directory, or they will be counted as
an extra file, not an optional file.
</p>
<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.
</p>
<p class="leftbar">
In other words, the actual amount of <strong>EXTRA</strong> files is 31.
</p>
<p class="leftbar">
Of course, if you use the optional filenames without
the files being our intended use, in order to get past the file limit, that
would be an abuse of rules. For more details on the optional files, see the
FAQ on the “<a href="../faq.html#try_script">try.sh script system</a>”
and the
FAQ on “<a href="../faq.html#alt_code">alt code</a>”.
</p>
<p class="leftbar">
If you do need to include more files, you may do so by including as an extra
file, a tarball. This does <strong>NOT</strong> have to pass <code>txzchk(1)</code> tests; only the
submission tarball must pass the <code>txzchk(1)</code> tests. See the <a href="#txzchk">txzchk
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.
</p>
<p class="leftbar">
<strong>IMPORTANT REMINDER</strong>: make <strong>SURE</strong> your tarball does <strong>NOT</strong> reveal who you are!
The <code>mkiocccentry(1)</code> tool creates a v7 format tarball to prevent this. You can
do the same like:
</p>
<pre><code> tar --format=v7 -cJf foo.txz directory</code></pre>
<p class="leftbar">
See <a href="rules.html#rule17">Rule 17</a> and in particular the part about the <a href="rules.html#max-files">maximum
number of files</a>. If you do not follow these points, you
are at a great risk of violating <a href="rules.html#rule17">Rule 17</a>!
</p>
<p class="leftbar">
<strong>NOTE</strong>: if you want to include a test-suite that requires a lot of files,
please suggest this in your <code>remarks.md</code> and if your submission wins it can
be done. In other words you should not use a tarball for a test-suite unless you
have a very good reason for this (and if you do, make <strong>SURE</strong> you specify why
in your <code>remarks.md</code>).
</p>
<h1 id="mkiocccentry"><code>mkiocccentry</code></h1>
<p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> (the <code>mkiocccentry(1)</code> rule) states that
@@ -1082,6 +1038,66 @@ Of course, as <code>txzchk</code> does not extract the tarball, it is possible t
manually package your submission tarball, you could still be violating <a href="rules.html#rule17">Rule
17</a>.
</p>
<div id="extra-files">
<h2 id="including-optional-and-extra-files">Including optional and extra files</h2>
</div>
<p class="leftbar">
The maximum total number of files that may be submitted has changed to 39 files.
However, of those files, 5 are mandatory (<code>prog.c</code>, <code>Makefile</code>, <code>remarks.md</code> and
the two JSON files generated by <code>mkiocccentry(1)</code>, <code>.info.json</code> and
<code>.auth.json</code>).
</p>
<p class="leftbar">
Additionally, three of the files, if included, <strong>MUST</strong> be
specific file(name)s and in the top level directory, or they will be counted as
an extra file, not an optional file.
</p>
<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.
</p>
<p class="leftbar">
In other words, the actual amount of <strong>EXTRA</strong> files is 31.
</p>
<p class="leftbar">
Of course, if you use the optional filenames without
the files being our intended use, in order to get past the file limit, that
would be an abuse of rules. For more details on the optional files, see the
FAQ on the “<a href="../faq.html#try_script">try.sh script system</a>”
and the
FAQ on “<a href="../faq.html#alt_code">alt code</a>”.
</p>
<p class="leftbar">
If you do need to include more files, you may do so by including as an extra
file, a tarball. This does <strong>NOT</strong> have to pass <code>txzchk(1)</code> tests; only the
submission tarball must pass the <code>txzchk(1)</code> tests. See the <a href="#txzchk">txzchk
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.
</p>
<p class="leftbar">
<strong>IMPORTANT REMINDER</strong>: make <strong>SURE</strong> your tarball does <strong>NOT</strong> reveal who you are!
The <code>mkiocccentry(1)</code> tool creates a v7 format tarball to prevent this. You can
do the same like:
</p>
<pre><code> tar --format=v7 -cJf foo.txz directory</code></pre>
<p class="leftbar">
See <a href="rules.html#rule17">Rule 17</a> and in particular the part about the <a href="rules.html#max-files">maximum
number of files</a>. If you do not follow these points, you
are at a great risk of violating <a href="rules.html#rule17">Rule 17</a>!
</p>
<p class="leftbar">
<strong>NOTE</strong>: if you want to include a test-suite that requires a lot of files,
please suggest this in your <code>remarks.md</code> and if your submission wins it can
be done. In other words you should not use a tarball for a test-suite unless you
have a very good reason for this (and if you do, make <strong>SURE</strong> you specify why
in your <code>remarks.md</code>).
</p>
<p class="leftbar">
See also the
FAQ on “<a href="../faq.html#txzchk">txzchk</a>”.
next/guidelines.md
+97 -78
View File
@@ -49,7 +49,7 @@ Jump to: [top](#)
</div>
<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.35 2025-01-30**.
These [IOCCC guidelines](guidelines.html) are version **28.36 2025-02-03**.
</p>
<p class="leftbar">
@@ -233,13 +233,30 @@ 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">
**IMPORTANT NOTE**: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
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 via `sudo` or as root).
</p>
<p class="leftbar">
[Rule 17](rules.html#rule17) has been **significantly modified**
to account for the new [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) tools.
Thus, you are **STRONGLY** advised to use the `mkiocccentry(1)` tool
as found in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
to form the file to upload to the [submit server](https://submit.ioccc.org). Not
doing so puts you at a very big risk of violating [Rule 17](rules.html#rule17).
using `mkiocccentry(1)` the [submit server](https://submit.ioccc.org). Uploading
a tarball not formed by `mkiocccentry(1)` puts you at a very big risk of
violating [Rule 17](rules.html#rule17), especially as `mkiocccentry(1)` does a
great number of things that are required, and it also runs many checks, and if
any of those checks fail, you are at a very great risk of having your submission
rejected for violating [Rule 17](rules.html#rule17).
</p>
@@ -485,81 +502,6 @@ are considered more portable.
Jump to: [top](#)
<div id="extra-files">
# Including optional and extra files
</div>
<p class="leftbar">
The maximum total number of files that may be submitted has changed to 39 files.
However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
`.auth.json`).
</p>
<p class="leftbar">
Additionally, three of the files, if included, **MUST** be
specific file(name)s and in the top level directory, or they will be counted as
an extra file, not an optional file.
</p>
<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.
</p>
<p class="leftbar">
In other words, the actual amount of **EXTRA** files is 31.
</p>
<p class="leftbar">
Of course, if you use the optional filenames without
the files being our intended use, in order to get past the file limit, that
would be an abuse of rules. For more details on the optional files, see the
FAQ on the "[try.sh script system](../faq.html#try_script)"
and the
FAQ on "[alt code](../faq.html#alt_code)".
</p>
<p class="leftbar">
If you do need to include more files, you may do so by including as an extra
file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
submission tarball must pass the `txzchk(1)` tests. See the [txzchk
section](#txzchk) for more details on this important tool.
</p>
<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.
</p>
<p class="leftbar">
**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
do the same like:
</p>
``` <!---sh-->
tar --format=v7 -cJf foo.txz directory
```
<p class="leftbar">
See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
number of files](rules.html#max-files). If you do not follow these points, you
are at a great risk of violating [Rule 17](rules.html#rule17)!
</p>
<p class="leftbar">
**NOTE**: if you want to include a test-suite that requires a lot of files,
please suggest this in your `remarks.md` and if your submission wins it can
be done. In other words you should not use a tarball for a test-suite unless you
have a very good reason for this (and if you do, make **SURE** you specify why
in your `remarks.md`).
</p>
<div id="mkiocccentry">
# `mkiocccentry`
</div>
@@ -818,6 +760,83 @@ manually package your submission tarball, you could still be violating [Rule
17](rules.html#rule17).
</p>
<div id="extra-files">
## Including optional and extra files
</div>
<p class="leftbar">
The maximum total number of files that may be submitted has changed to 39 files.
However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
`.auth.json`).
</p>
<p class="leftbar">
Additionally, three of the files, if included, **MUST** be
specific file(name)s and in the top level directory, or they will be counted as
an extra file, not an optional file.
</p>
<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.
</p>
<p class="leftbar">
In other words, the actual amount of **EXTRA** files is 31.
</p>
<p class="leftbar">
Of course, if you use the optional filenames without
the files being our intended use, in order to get past the file limit, that
would be an abuse of rules. For more details on the optional files, see the
FAQ on the "[try.sh script system](../faq.html#try_script)"
and the
FAQ on "[alt code](../faq.html#alt_code)".
</p>
<p class="leftbar">
If you do need to include more files, you may do so by including as an extra
file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
submission tarball must pass the `txzchk(1)` tests. See the [txzchk
section](#txzchk) for more details on this important tool.
</p>
<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.
</p>
<p class="leftbar">
**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
do the same like:
</p>
``` <!---sh-->
tar --format=v7 -cJf foo.txz directory
```
<p class="leftbar">
See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
number of files](rules.html#max-files). If you do not follow these points, you
are at a great risk of violating [Rule 17](rules.html#rule17)!
</p>
<p class="leftbar">
**NOTE**: if you want to include a test-suite that requires a lot of files,
please suggest this in your `remarks.md` and if your submission wins it can
be done. In other words you should not use a tarball for a test-suite unless you
have a very good reason for this (and if you do, make **SURE** you specify why
in your `remarks.md`).
</p>
<p class="leftbar">
See also the
FAQ on "[txzchk](../faq.html#txzchk)".
next/remarks.example.md
+27
View File
@@ -0,0 +1,27 @@
# Instructions
0. Create an empty file `remarks.md` in your submission directory
(alternatively after reading this file, delete everything in it and rename it
`remarks.md`).
1. For help with markdown format please see this [helpful
guide](https://www.markdownguide.org/basic-syntax/).
2. Please see and follow the [IOCCC markdown
guidelines](https://www.ioccc.org/markdown.html). Doing this helps the judges
integrate your remarks into a `README.md`, should you win.
3. After reading this file, write your remarks in your `remarks.md` file (as
mentioned in step 0).
4. When packaging your submission with `mkiocccentry(1)`, make sure that the
`remarks.md` is in the `topdir`.
**IMPORTANT NOTE**: make **SURE** you read the IOCCC
[Rules](https://www.ioccc.org/next/rules.html) and
[Guidelines](https://www.ioccc.org/next/guidelines.html)!
# What should you say?
Please see the
FAQ on "[what to put in your remarks](../faq.html#remarks)".
next/rules.html
+34 -17
View File
@@ -460,9 +460,8 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
<h2 id="ioccc-rules-version">IOCCC Rules version</h2>
</div>
</div>
<p>Jump to: <a href="#">top</a></p>
<p class="leftbar">
These <a href="rules.html">IOCCC rules</a> are version <strong>28.19 2025-01-30</strong>.
These <a href="rules.html">IOCCC rules</a> are version <strong>28.23 2025-02-10</strong>.
</p>
<p class="leftbar">
The <a href="rules.md" download="rules.md">markdown form of these rules</a>
@@ -973,8 +972,8 @@ if you need to include more files than this maximum.
<p class="leftbar">
Extra files are defined as files that are not the required files (<code>prog.c</code>,
<code>Makefile</code>, <code>remarks.md</code> and the two generated by <code>mkiocccentry(1)</code> <code>.info.json</code>
and <code>.auth.json</code>) and the optional files (<code>try.sh</code>, <code>prog.alt.c</code> and
<code>try.alt.sh</code>).
and <code>.auth.json</code>) and files that are also not the optional files (<code>try.sh</code>,
<code>prog.alt.c</code> and <code>try.alt.sh</code>).
</p>
<p>Jump to: <a href="#">top</a></p>
<h3 id="rule-17---the-complex-details">Rule 17 - The COMPLEX details</h3>
@@ -1044,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
@@ -1056,7 +1057,7 @@ 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 <strong>3999971</strong> octets in size.
The xz compressed tarball file <strong>MUST</strong> be less than or equal to <strong>3999971</strong> octets in size.
</p>
<p class="leftbar">
When your submission’s xz compressed tarball is uncompressed,
@@ -1092,11 +1093,10 @@ Filenames in your entry (that is, not including the files generated by the
</p>
<ul>
<li><p class="leftbar">
Be &lt;= <strong>38</strong> characters in length
Be &lt;= <strong>38</strong> characters in length.
</p></li>
<li><p class="leftbar">
<strong>NOT</strong> have a <strong><code>/</code></strong> (excluding the entry directory that
the <code>mkiocccentry(1)</code> tool generates).
<strong>NOT</strong> have a leading <strong><code>/</code></strong>.
</p></li>
<li><p class="leftbar">
<strong>NOT</strong> contain a path component of: <strong><code>.</code></strong> (that is, with
@@ -1116,12 +1116,12 @@ Match the regular expression
<strong>NOT</strong> be a directory depth &gt; 4.
</p></li>
<li><p class="leftbar">
<strong>NOT</strong> have a total path length &gt; 99 characters.
<strong>NOT</strong> have a total <strong>path</strong> length &gt; 99 characters.
</p></li>
</ul>
<p class="leftbar">
Additionally, the submission tarball created by <code>mkiocccentry(1)</code> <strong>MUST</strong> have
the following files (generated by the <code>mkiocccentry(1)</code> tool):
The submission tarball created by <code>mkiocccentry(1)</code> <strong>MUST</strong> have
the additional files that are generated by the <code>mkiocccentry(1)</code> tool:
</p>
<ul>
<li><p class="leftbar">
@@ -1134,11 +1134,27 @@ 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.
</p>
<p class="leftbar">
Files and directories in your submission tarball <strong>MUST</strong> be specific
permissions and <code>mkiocccentry(1)</code> does this for you. In particular: directories
<strong>MUST</strong> be <code>drwxr-xr-x</code> (i.e. <code>0755</code>), the optional files, <code>try.sh</code> or
<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
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 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
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
page</a>.
</p>
<p class="leftbar">
@@ -1162,7 +1178,8 @@ having your submission rejected for violating <a href="#rule17">Rule 17</a>!
<p class="leftbar">
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>) is 31. This is defined in the macro
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
<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
@@ -1251,7 +1268,7 @@ do this <strong>AFTER</strong> the <a href="../status.html">contest status</a> h
<p class="leftbar">
<strong><a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International</a></strong>
</p>
<p>You (the author(s)) <strong>MUST</strong> own the contents of your submission <strong>OR</strong>
<p>You (the author(s)) <strong>MUST</strong> own the content of your submission <strong>OR</strong>
you <strong>MUST HAVE PERMISSION</strong> from the owner(s) to submit their content.</p>
<p>You <strong>MUST NOT</strong> submit anything that cannot be submitted under that license.</p>
<p>Jump to: <a href="#">top</a></p>
@@ -1278,7 +1295,7 @@ guidelines</a> for additional markdown guidance.
make(1) compatibility the IOCCC
supports</a> for more details.</p>
<p class="leftbar">
You are <strong>ENCOURAGED</strong> to use
You are <strong>ENCOURAGED</strong> to use the
Makefile example, renamed as <code>Makefile</code> of course, for help in constructing your
<code>Makefile</code>. See the <a href="guidelines.html#makefile">Makefile section</a> in the
guidelines for more details.
next/rules.md
+36 -21
View File
@@ -51,11 +51,9 @@ Jump to: [top](#)
</div>
Jump to: [top](#)
<p class="leftbar">
These [IOCCC rules](rules.html) are version **28.19 2025-01-30**.
These [IOCCC rules](rules.html) are version **28.23 2025-02-10**.
</p>
<p class="leftbar">
@@ -747,8 +745,8 @@ if you need to include more files than this maximum.
<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 the optional files (`try.sh`, `prog.alt.c` and
`try.alt.sh`).
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](#)
@@ -821,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
@@ -835,7 +835,7 @@ and the [CommonMark Spec](https://spec.commonmark.org/current/).
</p>
<p class="leftbar">
The xz compressed tarball file **MUST** be less than or equal **3999971** octets in size.
The xz compressed tarball file **MUST** be less than or equal to **3999971** octets in size.
</p>
<p class="leftbar">
@@ -850,8 +850,6 @@ Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
the [guidelines](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
@@ -861,7 +859,6 @@ 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](guidelines.html) for
@@ -880,9 +877,8 @@ 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 **`/`** (excluding the entry directory that
the `mkiocccentry(1)` tool generates).</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** **`.`**).</p>
@@ -892,11 +888,11 @@ the exception of files generated by `mkiocccentry(1)` itself, it must have
`^[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">**NOT** have a total **path** length > 99 characters.</p>
<p class="leftbar">
Additionally, the submission tarball created by `mkiocccentry(1)` **MUST** have
the following files (generated by the `mkiocccentry(1)` tool):
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
@@ -904,12 +900,30 @@ 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 _prior to_ the tarball
being formed.
</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](#rule17)! 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 is very
**possibly** a bug; please [report it as a bug at the mkiocccentry issues
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>
@@ -938,7 +952,8 @@ having your submission rejected for violating [Rule 17](#rule17)!
<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`) is 31. This is defined in the macro
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
@@ -1049,7 +1064,7 @@ The entirety of your submission must be submitted under the following license:
**[CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/)**
</p>
You (the author(s)) **MUST** own the contents of your submission **OR**
You (the author(s)) **MUST** own the content of your submission **OR**
you **MUST HAVE PERMISSION** from the owner(s) to submit their content.
You **MUST NOT** submit anything that cannot be submitted under that license.
@@ -1090,7 +1105,7 @@ make&lpar;1&rpar; compatibility the IOCCC
supports](../faq.html#make_compatibility) for more details.
<p class="leftbar">
You are **ENCOURAGED** to use
You are **ENCOURAGED** to use the
Makefile example, renamed as `Makefile` of course, for help in constructing your
`Makefile`. See the [Makefile section](guidelines.html#makefile) in the
guidelines for more details.
next/try.alt.sh
Regular → Executable
View File
File mode changed.
next/try.sh
Regular → Executable
View File
File mode changed.
quick-start.html
+26 -12
View File
@@ -512,21 +512,25 @@ the
FAQ on”<a href="#using_mkiocccentry">how to use mkiocccentry</a>“)
and the <a href="next/guidelines.html#mkiocccentry">mkiocccentry section in the
guidelines</a>.</p>
<pre><code> mkiocccentry work_dir prog.c Makefile remarks.md [file ...]</code></pre>
<pre><code> mkiocccentry [options] workdir topdir</code></pre>
<p>where:</p>
<ul>
<li><p><code>work_dir</code></p>
<p>directory where the entry directory and tarball are formed</p></li>
<li><p><code>workdir</code></p>
<p>directory where the submission directory and tarball are formed</p></li>
<li><p><code>topdir</code></p>
<p>directory where your files to be packaged are in</p></li>
</ul>
<p>Three files are required to exist in <code>topdir</code>:</p>
<ul>
<li><p><code>prog.c</code></p>
<p>path to the C source for your entry</p></li>
<p>path to the C source for your submission</p></li>
<li><p><code>Makefile</code></p>
<p>Makefile to build (make all) and cleanup (make clean &amp; make clobber)</p></li>
<p>Makefile to build (make all) and cleanup (make clean &amp; make clobber) as well
as the other required rules</p></li>
<li><p><code>remarks.md</code></p>
<p>Remarks about your entry in markdown format: see the
FAQ on “<a href="#remarks_md">remarks.md</a>”
FAQ on “<a href="faq.html#remarks_md">remarks.md</a>”
for more info.</p></li>
<li><p>[file …]</p>
<p>Optional extra data files to include with your entry</p></li>
</ul>
<p><strong>NOTE</strong>: Please see our <a href="markdown.html">IOCCC markdown guide</a> for <strong>important information</strong> on using markdown in the IOCCC.</p>
<p><strong>NOTE</strong>: It is <em>NOT</em> necessary to install the tools to use them as you can run
@@ -536,10 +540,20 @@ However, installing it will make it easier for you as you can run it from your
submission’s directory. See the
FAQ on “<strong><a href="https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install">installing mkiocccentry</a></strong>”
at the mkiocccentry repo.</p>
<p>If the <code>mkiocccentry</code> tool indicates that there is a problem with your entry,
especially if it identifies a <a href="next/rules.html#rule2">Rule 2</a>, or any other
rule, related problem, you are <strong>strongly</strong> encouraged to revise and correct
your entry and then re-run the <code>mkiocccentry</code> tool.</p>
<p>However, an <strong>IMPORTANT NOTE</strong>: if you run the program outside the repo
directory (specifying the absolute or relative path to the tool) and you
have not installed the tools then you will have to specify the options for the
tools that are required like <code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fnamchk(1)</code>. 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 <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).</p>
<p>If the <code>mkiocccentry</code> tool indicates that there is a problem with your
submission, especially if it identifies a <a href="next/rules.html#rule2">Rule 2</a>, or
any other rule, related problem, you are <strong>strongly</strong> encouraged to revise and
correct your entry and then re-run the <code>mkiocccentry</code> tool.</p>
<p>If you choose to risk violating rules, be sure and explain your reason
for doing so in your <code>remarks.md</code> file.</p>
<p>See also <a href="next/rules.html#rule17">Rule 17</a>!</p>
quick-start.md
+28 -14
View File
@@ -124,33 +124,36 @@ guidelines](next/guidelines.html#mkiocccentry).
``` <!---sh-->
mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
mkiocccentry [options] workdir topdir
```
where:
* `work_dir`
* `workdir`
directory where the entry directory and tarball are formed
directory where the submission directory and tarball are formed
* `topdir`
directory where your files to be packaged are in
Three files are required to exist in `topdir`:
* `prog.c`
path to the C source for your entry
path to the C source for your submission
* `Makefile`
Makefile to build (make all) and cleanup (make clean & make clobber)
Makefile to build (make all) and cleanup (make clean & make clobber) as well
as the other required rules
* `remarks.md`
Remarks about your entry in markdown format: see the
FAQ on "[remarks.md](#remarks_md)"
FAQ on "[remarks.md](faq.html#remarks_md)"
for more info.
* [file ...]
Optional extra data files to include with your entry
**NOTE**: Please see our [IOCCC markdown guide](markdown.html) for **important information** on using markdown in the IOCCC.
**NOTE**: It is *NOT* necessary to install the tools to use them as you can run
@@ -161,10 +164,21 @@ submission's directory. See the
FAQ on "**[installing mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install)**"
at the mkiocccentry repo.
If the `mkiocccentry` tool indicates that there is a problem with your entry,
especially if it identifies a [Rule 2](next/rules.html#rule2), or any other
rule, related problem, you are **strongly** encouraged to revise and correct
your entry and then re-run the `mkiocccentry` tool.
However, an **IMPORTANT NOTE**: if you run the program outside the repo
directory (specifying the absolute or relative path to the tool) and you
have not installed the tools then you will have to specify the options for the
tools that 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 via `sudo` or as root).
If the `mkiocccentry` tool indicates that there is a problem with your
submission, especially if it identifies a [Rule 2](next/rules.html#rule2), or
any other rule, related problem, you are **strongly** encouraged to revise and
correct your entry and then re-run the `mkiocccentry` tool.
If you choose to risk violating rules, be sure and explain your reason
for doing so in your `remarks.md` file.