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

Update FAQ, guidelines and quick start

Browse Source 
This addresses most (if not all) of the recent changes to chkentry(1)
though a more thorough check will be made later after the mkiocccentry
code freeze.
This commit is contained in:
Cody Boone Ferguson committed 2025-02-27 14:56:01 -08:00
1 parent c5adf3016b
commit 65cf447087
6 files changed
+324 -236
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+48 -25
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.10 2025-02-26</strong>.</p>
<p>This is FAQ version <strong>28.2.11 2025-02-27</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>
@@ -434,7 +434,8 @@
<li><strong>Q 0.1.1</strong>: <a class="normal" href="#about_mkiocccentry">What is <code>mkiocccentry(1)</code> in simple terms?</a></li>
<li><strong>Q 0.1.2</strong>: <a class="normal" href="#obtaining_mkiocccentry">How do I obtain the latest mkiocccentry toolkit?</a></li>
<li><strong>Q 0.1.3</strong>: <a class="normal" href="#compiling_mkiocccentry">How do I compile the mkiocccentry toolkit?</a></li>
<li><strong>Q 0.1.4</strong>: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a></li>
<li><strong>Q 0.1.4</strong>: <a class="normal" href="#install">How do I install mkiocccentry(1) and related tools?</a></li>
<li><strong>Q 0.1.5</strong>: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a></li>
</ul></li>
<li><strong>Q 0.2</strong>: <a class="normal" href="#platform">What platform should I assume for my submission?</a></li>
<li><strong>Q 0.3</strong>: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a></li>
@@ -480,6 +481,7 @@
<li><strong>Q 3.9</strong>: <a class="normal" href="#entry_id_faq">What is an <code>entry_id</code>?</a></li>
<li><strong>Q 3.10</strong>: <a class="normal" href="#entry_json">What is a <code>.entry.json</code> file and how is it used?</a></li>
<li><strong>Q 3.11</strong>: <a class="normal" href="#jparse">How can I validate any JSON document?</a></li>
<li><strong>Q 3.12</strong>: <a class="normal" href="#install">How can I install the <code>mkiocccentry(1)</code> and related tools?</a></li>
</ul>
<h2 id="compiling-ioccc-entries">4. <a href="#compiling">Compiling IOCCC entries</a></h2>
<ul>
@@ -680,17 +682,43 @@ have an mkiocccentry tool directory:</p>
<p>Once you’ve obtained the <strong>LATEST</strong> version (see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the latest mkiocccentry toolkit</a>”
to make sure of this), change to the <code>mkiocccentry</code> directory and then run:</p>
<pre><code> make clobber all test</code></pre>
<p>to compile all the tools and run the test-suite.</p>
<p>You do not have to run the test-suite but if you wish to make sure all is in
order you may. If you wish to skip that:</p>
<pre><code> make clobber all</code></pre>
<p>to compile all the tools.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="install">
<h3 id="q-0.1.4-how-do-i-install-mkiocccentry1-and-related-tools">Q 0.1.4: How do I install mkiocccentry(1) and related tools?</h3>
</div>
<p>After obtaining the toolkit (see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the latest mkiocccentry toolkit</a>”)
and compiling the tools (see the
FAQ on “<a href="#compiling_mkiocccentry">compiling mkiocccentry</a>”
above) run as either <code>sudo(8)</code> or root <code>make install</code>:</p>
<pre><code> # if you use sudo(8):
sudo make install
# as root:
make install</code></pre>
<p>If everything goes well you should be able to run <code>mkiocccentry(1)</code>,
<code>txzchk(1)</code>, <code>chkentry(1)</code> and all the other installed tools from any directory,
and the tools that rely on other tools will be able to find those required tools
from any directory too.</p>
<p>Some tools like <code>bug_report.sh</code> and <code>hostchk.sh</code> are not meant to be installed
and will not work from any directory, however.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="using_mkiocccentry">
<h4 id="q-0.1.4-how-do-i-use-mkiocccentry">Q 0.1.4: How do I use mkiocccentry?</h4>
<h4 id="q-0.1.5-how-do-i-use-mkiocccentry">Q 0.1.5: How do I use mkiocccentry?</h4>
</div>
<p>Once you have registered, you will need to package your entry with the
<code>mkiocccentry</code> tool. If you have not already obtained the toolkit, see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the mkiocccentry toolkit</a>”
and the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the most recent mkiocccentry
toolkit</a>”,
the
FAQ on “<a href="#compiling_mkiocccentry">compiling mkiocccentry</a>”
and the
FAQ on “<a href="#installing">installing the mkiocccentry tools</a>”
if you have not already done so.</p>
<p>The below details discuss this very important tool. As it is complicated we will
explain how to use this tool. If you want to know what it is in simpler terms,
@@ -709,15 +737,10 @@ the timestamp; see the <a href="next/rules.html">rules</a> for more details on t
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). We recommend you install
the tools but if you wish to run it from the repo directory you may.</p>
installed the tools (and we <strong>STRONGLY</strong> recommend you <strong>do</strong> install them),
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>. And remember to make sure you have
the latest version so you do not violate <a href="next/rules.html#rule17">Rule 17</a>.</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 subdirectory), as it needs to be
@@ -1741,16 +1764,14 @@ you can do so. For instance:</p>
FAQ on “<a href="#txzchk">validating your submission tarball</a>”
for more information.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="validating_auth_info_json">
<div id="chkentry">
<h3 id="q-3.3-how-can-i-validate-my-submission-directory">Q 3.3: How can I validate my submission directory?</h3>
</div>
</div>
<p>If you want to validate your submission directory manually, including but not
limited to the <code>.auth.json</code> or <code>.info.json</code> files, you should use <code>chkentry(1)</code>
limited to the <code>.auth.json</code> and <code>.info.json</code> files, you should use <code>chkentry(1)</code>
from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>.</p>
<p>The <code>chkentry(1)</code> tool runs a variety of checks on your submission directory,
including but not limited to, using the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3">jparse
including, but not limited to, using the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3">jparse
API</a>
to validate the two IOCCC specific JSON files (as valid JSON) and additional
checks on those files as well. An important thing that it does is verify that
@@ -1768,12 +1789,14 @@ and
FAQ on “<a href="#info_json">.info.json</a>”
for more details on the two required and very important JSON files.</p>
<p>The <code>chkentry(1)</code> tool accepts a single arg, a directory that <strong>MUST</strong> have the
two JSON files, <code>.auth.json</code> and <code>.info.json</code>. (Okay there is an option to skip
files but this is for the judges <strong>ONLY</strong>; use of this option to validate your
submission puts you at a great risk of violating <a href="next/rules.html#rule17">Rule
17</a>!).</p>
<p>As an example, if your submission directory is <code>12345678-1234-4321-abcd-1234567890ab-0/</code> then you should run the
following command:</p>
two JSON files, <code>.auth.json</code> and <code>.info.json</code> as well as the <code>prog.c</code>,
<code>Makefile</code> and <code>remarks.md</code> files along with all the other files listed in the
<code>.info.json</code> manifest. (Okay there is an option to skip files but this is for
the judges <strong>ONLY</strong>; use of this option to validate your submission puts you at
a great risk of violating <a href="next/rules.html#rule17">Rule 17</a>!).</p>
<p>As an example, if your submission directory is
<code>12345678-1234-4321-abcd-1234567890ab-0/</code> then you should run the following
command:</p>
<pre><code> chkentry 12345678-1234-4321-abcd-1234567890ab-0</code></pre>
<p>If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected by the
<code>jparse(3)</code> API (i.e. it is not valid JSON) it is an error and <code>chkentry(1)</code>
faq.md
+67 -25
View File
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
This is FAQ version **28.2.10 2025-02-26**.
This is FAQ version **28.2.11 2025-02-27**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -9,7 +9,8 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 0.1.1**: <a class="normal" href="#about_mkiocccentry">What is `mkiocccentry(1)` in simple terms?</a>
- **Q 0.1.2**: <a class="normal" href="#obtaining_mkiocccentry">How do I obtain the latest mkiocccentry toolkit?</a>
- **Q 0.1.3**: <a class="normal" href="#compiling_mkiocccentry">How do I compile the mkiocccentry toolkit?</a>
- **Q 0.1.4**: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a>
- **Q 0.1.4**: <a class="normal" href="#install">How do I install mkiocccentry(1) and related tools?</a>
- **Q 0.1.5**: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a>
- **Q 0.2**: <a class="normal" href="#platform">What platform should I assume for my submission?</a>
- **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>
@@ -54,6 +55,7 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 3.9**: <a class="normal" href="#entry_id_faq">What is an `entry_id`?</a>
- **Q 3.10**: <a class="normal" href="#entry_json">What is a `.entry.json` file and how is it used?</a>
- **Q 3.11**: <a class="normal" href="#jparse">How can I validate any JSON document?</a>
- **Q 3.12**: <a class="normal" href="#install">How can I install the `mkiocccentry(1)` and related tools?</a>
## 4. [Compiling IOCCC entries](#compiling)
@@ -289,23 +291,66 @@ Once you've obtained the **LATEST** version (see the
FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)"
to make sure of this), change to the `mkiocccentry` directory and then run:
``` <!---sh-->
make clobber all test
```
to compile all the tools and run the test-suite.
You do not have to run the test-suite but if you wish to make sure all is in
order you may. If you wish to skip that:
``` <!---sh-->
make clobber all
```
to compile all the tools.
Jump to: [top](#)
<div id="install">
### Q 0.1.4: How do I install mkiocccentry(1) and related tools?
</div>
After obtaining the toolkit (see the
FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)")
and compiling the tools (see the
FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)"
above) run as either `sudo(8)` or root `make install`:
``` <!---sh-->
# if you use sudo(8):
sudo make install
# as root:
make install
```
If everything goes well you should be able to run `mkiocccentry(1)`,
`txzchk(1)`, `chkentry(1)` and all the other installed tools from any directory,
and the tools that rely on other tools will be able to find those required tools
from any directory too.
Some tools like `bug_report.sh` and `hostchk.sh` are not meant to be installed
and will not work from any directory, however.
Jump to: [top](#)
<div id="using_mkiocccentry">
#### Q 0.1.4: How do I use mkiocccentry?
#### Q 0.1.5: How do I use mkiocccentry?
</div>
Once you have registered, you will need to package your entry with the
`mkiocccentry` tool. If you have not already obtained the toolkit, see the
FAQ on "[obtaining the mkiocccentry toolkit](#obtaining_mkiocccentry)"
and the
FAQ on "[obtaining the most recent mkiocccentry
toolkit](#obtaining_mkiocccentry)",
the
FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)"
and the
FAQ on "[installing the mkiocccentry tools](#installing)"
if you have not already done so.
The below details discuss this very important tool. As it is complicated we will
@@ -332,15 +377,10 @@ 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). We recommend you install
the tools but if you wish to run it from the repo directory you may.
installed the tools (and we **STRONGLY** recommend you **do** install them),
then you will have to specify the options for the tools that are required like
`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
the latest version so you do not violate [Rule 17](next/rules.html#rule17).
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
@@ -1584,18 +1624,16 @@ for more information.
Jump to: [top](#)
<div id="validating_auth_info_json">
<div id="chkentry">
### Q 3.3: How can I validate my submission directory?
</div>
</div>
If you want to validate your submission directory manually, including but not
limited to the `.auth.json` or `.info.json` files, you should use `chkentry(1)`
limited to the `.auth.json` and `.info.json` files, you should use `chkentry(1)`
from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
The `chkentry(1)` tool runs a variety of checks on your submission directory,
including but not limited to, using the [jparse
including, but not limited to, using the [jparse
API](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3)
to validate the two IOCCC specific JSON files (as valid JSON) and additional
checks on those files as well. An important thing that it does is verify that
@@ -1616,13 +1654,15 @@ FAQ on "[.info.json](#info_json)"
for more details on the two required and very important JSON files.
The `chkentry(1)` tool accepts a single arg, a directory that **MUST** have the
two JSON files, `.auth.json` and `.info.json`. (Okay there is an option to skip
files but this is for the judges **ONLY**; use of this option to validate your
submission puts you at a great risk of violating [Rule
17](next/rules.html#rule17)!).
two JSON files, `.auth.json` and `.info.json` as well as the `prog.c`,
`Makefile` and `remarks.md` files along with all the other files listed in the
`.info.json` manifest. (Okay there is an option to skip files but this is for
the judges **ONLY**; use of this option to validate your submission puts you at
a great risk of violating [Rule 17](next/rules.html#rule17)!).
As an example, if your submission directory is `12345678-1234-4321-abcd-1234567890ab-0/` then you should run the
following command:
As an example, if your submission directory is
`12345678-1234-4321-abcd-1234567890ab-0/` then you should run the following
command:
``` <!---sh-->
@@ -3557,6 +3597,7 @@ something along those lines.
Jump to: [top](#)
<div id="validating_json">
<div id="jparse">
### Q 3.11: How can I validate any JSON document?
@@ -3612,6 +3653,7 @@ as the two can be different at times.
Jump to: [top](#)
<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">
next/guidelines.html
+74 -62
View File
@@ -462,7 +462,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.39 2025-02-26</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.40 2025-02-27</strong>.
</p>
<p class="leftbar">
The markdown form of these guidelines <a href="guidelines.md"
@@ -613,15 +613,19 @@ normal mode.
<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). We recommend you install
the tools but if you wish to run it from the repo directory you may.
installed the tools (and we <strong>STRONGLY</strong> recommend you <strong>do</strong> install them),
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>. And remember to make sure you have
the latest version so you do not violate <a href="rules.html#rule17">Rule 17</a>.
See the
FAQ on “<a href="../faq.html#obtaining_mkiocccentry">obtaining the latest mkiocccentry tools</a>”,
the
FAQ on “<a href="../faq.html#compiling_mkiocccentry">compiling the mkiocccentry tools</a>”,
the
FAQ on “<a href="../faq.html#installing">installing the mkiocccentry tools</a>”
and the
FAQ on “<a href="../faq.html#using_mkiocccentry">using the mkiocccentry tools</a>”
for more help.
</p>
<p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> has been <strong>significantly modified</strong>
@@ -858,9 +862,10 @@ its algorithm.
<p class="leftbar">
If <code>mkiocccentry</code> encounters an <strong>error</strong> the program will exit and the xz
compressed tarball <strong>will not be formed</strong>. For instance, if
<a href="#chkentry">chkentry</a> fails to validate the <code>.auth.json</code> or <code>.info.json</code>
<a href="https://www.json.org/json-en.html">JSON</a> files (see below) that
<code>mkiocccentry(1)</code> creates, or anything else <code>mkiocccentry(1)</code> does, it is an
<a href="#chkentry">chkentry</a> fails to validate the submission directory, either because
of a validation error in the <code>.auth.json</code> or <code>.info.json</code>
<a href="https://www.json.org/json-en.html">JSON</a> files or because of
something else that <code>mkiocccentry(1)</code> creates or does, it is an
<strong>error</strong> and <strong>possibly</strong> a bug that you should <a href="https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&amp;labels=bug&amp;projects=&amp;template=bug_report.yml&amp;title=%5BBug%5D+%3Ctitle%3E">report as a bug at the
mkiocccentry bug report
page</a>.
@@ -931,7 +936,17 @@ checks described above are still made but through <code>mkiocccentry</code> itse
<p class="leftbar">
<code>mkiocccentry(1)</code> will write two JSON files: <code>.auth.json</code> and
<code>.info.json</code>. These files contain information about the author(s) and about the
submission. These files <strong>MUST</strong> pass the checks of <code>chkentry(1)</code>!
submission. After these files are formed, the <code>chkentry(1)</code> tool will be run on
the submission directory; this tool not only validates the two JSON files
(running specific checks on them after validating the JSON), but it also
verifies that what is in the manifest in <code>.info.json</code> matches the contents of
the directory, in addition to other checks. If <code>chkentry(1)</code> fails to validate
anything at all, your submission <strong>WILL BE</strong> rejected!
</p>
<p class="leftbar">
<strong>IMPORTANT</strong>: although <code>chkentry(1)</code> validates the files in the directory, it
only inspects the contents of the two JSON files; it performs other checks on
the other files, and those checks are run on the two JSON files as well.
</p>
<p class="leftbar">
If <code>chkentry</code> does not pass and you used <code>mkiocccentry(1)</code> it is <strong>very likely</strong> a
@@ -941,26 +956,21 @@ page</a>.
</p>
<pre><code> make bug_report</code></pre>
<p class="leftbar">
from the top level repo directory itself.
See also the
from the top level repo directory itself and attach the bug report file (it will
tell you the name of the file). See also the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
Assuming that <code>chkentry(1)</code> successfully validates both <code>.auth.json</code> and
<code>.info.json</code>, then the tarball will be formed and then <code>txzchk(1)</code> will be
executed on it. In this case, there should be no problems, as <code>mkiocccentry(1)</code> should
<strong>NOT</strong> form a tarball if there are any issues.
</p>
<p class="leftbar">
<strong>NOTE</strong>: <code>chkentry(1)</code> also validates other things in your submission
directory.
Assuming that <code>chkentry(1)</code> successfully validates your submission directory,
the tarball will be formed and then <code>txzchk(1)</code> will be executed on it. In this
case, there should be no problems, as <code>mkiocccentry(1)</code> should <strong>NOT</strong> form a
tarball if there are any issues.
</p>
<p class="leftbar">
If <code>mkiocccentry(1)</code> is used and <code>chkentry(1)</code> fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, though this is quite
unlikely. Nonetheless, if you believe there is a bug, you may report it as
explained above.
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, although this is unlikely.
Nonetheless, if you believe there is a bug, you may report it as explained above.
</p>
<p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the
@@ -983,13 +993,12 @@ jparse</a>, for more
details.
</p>
<p class="leftbar">
The <code>jparse</code> parser, library and tools were co-developed by
<a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a> and
<a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a> in 2022 and come
from the <a href="https://github.com/xexyl/jparse">jparse repo</a>. However, the
<strong>mkiocccentry tools use a <em>clone</em></strong> of the <a href="https://github.com/xexyl/jparse">jparse
repo</a> <strong>at a <em>specific</em> release</strong>.
Thus the <code>mkiocccentry</code> will at times be behind the
The <code>jparse</code> parser, library and tools were co-developed by <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone
Ferguson</a> and <a href="http://www.isthe.com/chongo/index.html">Landon Curt
Noll</a> in 2022-2025 and come from the
<a href="https://github.com/xexyl/jparse">jparse repo</a>. However, the <strong>mkiocccentry
tools use a <em>clone</em></strong> of the <a href="https://github.com/xexyl/jparse">jparse repo</a> <strong>at
a <em>specific</em> release</strong>. Thus the <code>mkiocccentry</code> will at times be behind the
<a href="https://github.com/xexyl/jparse">jparse repo</a>!
</p>
<p class="leftbar">
@@ -1017,10 +1026,8 @@ make sure that you’re using the correct versions, which is also verified by
</p>
<p class="leftbar">
Please see the
FAQ on “<a href="../faq.html#chkentry">validating .auth.json and/or .info.json files</a>
for more details on <code>chkentry</code> and how you can use it to validate your
<code>.auth.json</code> and <code>.info.json</code> files (and your submission directory in general)
manually, without having to repackage your submission.
FAQ on “<a href="../faq.html#chkentry">validating your submission directory</a>
for more details on <code>chkentry</code>.
</p>
<p class="leftbar">
You might also wish to see the
@@ -1944,46 +1951,51 @@ some Intel-like x86 architecture**.
The IOCCC size tool source is not an original work, unless you are <a href="../authors.html#Anthony_C_Howe">Anthony C
Howe</a>, in which case it is original! :-)
Submitting source code that uses the content of
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>, unless you are
<a href="../authors.html#Anthony_C_Howe">Anthony C Howe</a>, might run the risk of
violating <a href="rules.html#rule7">Rule 7</a>.
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c">iocccsize.c</a>,
<em>unless</em> you are <a href="../authors.html#Anthony_C_Howe">Anthony C Howe</a>, might run the
risk of violating <a href="rules.html#rule7">Rule 7</a>.
</p>
<p class="leftbar">
The <code>txzchk(1)</code> tool source is not an original work,
The IOCCC submission tarball validator source is not an original work,
unless you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a>, in
which case it is original! :-) Submitting source code that uses the contents of
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">txzchk.c</a>,
unless you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a>, might
<em>unless</em> you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a>, might
run the risk of violating <a href="rules.html#rule7">Rule 7</a>.
</p>
<p class="leftbar">
Neither the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c">chkentry tool
source</a> nor
the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">JSON parser and
library</a>
nor
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c">jstrencode</a>
nor
In addition to the above tools, none of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
tools</a>, <em>including, <strong>but not
limited</strong></em> to
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/mkiocccentry.c">mkiocccentry</a>,
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c">chkentry</a>,
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c">fnamchk</a>
and
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/location_main.c">location</a>,
nor the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">JSON parser and
library</a>,
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c">jstrencode</a>,
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrdecode.c">jstrdecode</a>
nor any of the other <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse">jparse
or any of the other <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse">jparse
tools</a>
(see the <a href="https://github.com/xexyl/jparse/">jparse repo</a>), nor the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c">fnamchk tool
source</a>,
are original works,
(see the <a href="https://github.com/xexyl/jparse/">jparse repo</a>), are original works,
unless you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a> or
<a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a>, in which case they
are original! :-) Submitting source code that uses the code of any of these tools or
library, unless you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone
are original! :-) Submitting source code that uses the content of any of these tools or
library, <em>unless</em> you are <a href="../authors.html#Cody_Boone_Ferguson">Cody Boone
Ferguson</a> or <a href="http://www.isthe.com/chongo/index.html">Landon Curt
Noll</a>, might run the risk of violating
<a href="rules.html#rule7">Rule 7</a>.
</p>
<p class="leftbar">
Unless you are <a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a>, the
remaining tools in the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>
are <strong>NOT</strong> original works. Submitting source code that uses the content of those tools,
unless you are <a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a>, might
run the risk of violating <a href="rules.html#rule7">Rule 7</a>.
And unless you are <a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a>,
the code in
<a href="https://github.com/ioccc-src/mkiocccentry/tree/master/dbg">dbg</a> and
<a href="https://github.com/ioccc-src/mkiocccentry/tree/master/dyn_array">dyn_array</a> are
not original works. Submitting source code that uses the content of those
libraries, <em>unless</em> you <a href="http://www.isthe.com/chongo/index.html">Landon Curt
Noll</a>, might run the risk of violating
<a href="rules.html#rule7">Rule 7</a>.
</p>
<p class="leftbar">
<a href="rules.html#rule7">Rule 7</a> does not prohibit you from writing your own
@@ -1999,7 +2011,7 @@ mind that writing an obfuscated version of a library runs the risk of violating
<p class="leftbar">
Even so, we do not recommend you try and submit a JSON parser due to
the fact it will likely exceed <a href="rules.html#rule2">the source code size limit</a>
and because you likely can’t beat <a href="https://github.com/westes/flex">flex</a> or
and because you likely can’t beat <a href="https://github.com/westes/flex">flex</a> and
<a href="https://www.gnu.org/software/bison/">bison</a> in obfuscation. This isn’t to
say that <a href="https://github.com/xexyl/jparse/blob/master/json_README.md#so-called-json-spec">the so-called JSON spec</a> is not
obfuscated, but unless you have some really clever way to compact and
next/guidelines.md
+75 -64
View File
@@ -50,7 +50,7 @@ Jump to: [top](#)
</div>
<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.39 2025-02-26**.
These [IOCCC guidelines](guidelines.html) are version **28.40 2025-02-27**.
</p>
<p class="leftbar">
@@ -238,15 +238,19 @@ normal mode.
<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). We recommend you install
the tools but if you wish to run it from the repo directory you may.
installed the tools (and we **STRONGLY** recommend you **do** install them),
then you will have to specify the options for the tools that are required like
`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
the latest version so you do not violate [Rule 17](rules.html#rule17).
See the
FAQ on "[obtaining the latest mkiocccentry tools](../faq.html#obtaining_mkiocccentry)",
the
FAQ on "[compiling the mkiocccentry tools](../faq.html#compiling_mkiocccentry)",
the
FAQ on "[installing the mkiocccentry tools](../faq.html#installing)"
and the
FAQ on "[using the mkiocccentry tools](../faq.html#using_mkiocccentry)"
for more help.
</p>
<p class="leftbar">
@@ -535,9 +539,10 @@ its algorithm.
<p class="leftbar">
If `mkiocccentry` encounters an **error** the program will exit and the xz
compressed tarball **will not be formed**. For instance, if
[chkentry](#chkentry) fails to validate the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files (see below) that
`mkiocccentry(1)` creates, or anything else `mkiocccentry(1)` does, it is an
[chkentry](#chkentry) fails to validate the submission directory, either because
of a validation error in the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files or because of
something else that `mkiocccentry(1)` creates or does, it is an
**error** and **possibly** a bug that you should [report as a bug at the
mkiocccentry bug report
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
@@ -632,7 +637,18 @@ Jump to: [top](#)
<p class="leftbar">`mkiocccentry(1)` will write two JSON files: `.auth.json` and
`.info.json`. These files contain information about the author(s) and about the
submission. These files **MUST** pass the checks of `chkentry(1)`!
submission. After these files are formed, the `chkentry(1)` tool will be run on
the submission directory; this tool not only validates the two JSON files
(running specific checks on them after validating the JSON), but it also
verifies that what is in the manifest in `.info.json` matches the contents of
the directory, in addition to other checks. If `chkentry(1)` fails to validate
anything at all, your submission **WILL BE** rejected!
</p>
<p class="leftbar">
**IMPORTANT**: although `chkentry(1)` validates the files in the directory, it
only inspects the contents of the two JSON files; it performs other checks on
the other files, and those checks are run on the two JSON files as well.
</p>
<p class="leftbar">
@@ -647,29 +663,23 @@ page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
```
<p class="leftbar">
from the top level repo directory itself.
See also the
from the top level repo directory itself and attach the bug report file (it will
tell you the name of the file). See also the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
<p class="leftbar">
Assuming that `chkentry(1)` successfully validates both `.auth.json` and
`.info.json`, then the tarball will be formed and then `txzchk(1)` will be
executed on it. In this case, there should be no problems, as `mkiocccentry(1)` should
**NOT** form a tarball if there are any issues.
</p>
<p class="leftbar">
**NOTE**: `chkentry(1)` also validates other things in your submission
directory.
Assuming that `chkentry(1)` successfully validates your submission directory,
the tarball will be formed and then `txzchk(1)` will be executed on it. In this
case, there should be no problems, as `mkiocccentry(1)` should **NOT** form a
tarball if there are any issues.
</p>
<p class="leftbar">
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate your submission
directory, then unless it is a system specific problem, it could be a bug in
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though this is quite
unlikely. Nonetheless, if you believe there is a bug, you may report it as
explained above.
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, although this is unlikely.
Nonetheless, if you believe there is a bug, you may report it as explained above.
</p>
<p class="leftbar">
@@ -695,13 +705,12 @@ details.
</p>
<p class="leftbar">
The `jparse` parser, library and tools were co-developed by
[Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) and
[Landon Curt Noll](http://www.isthe.com/chongo/index.html) in 2022 and come
from the [jparse repo](https://github.com/xexyl/jparse). However, the
**mkiocccentry tools use a _clone_** of the [jparse
repo](https://github.com/xexyl/jparse) **at a _specific_ release**.
Thus the `mkiocccentry` will at times be behind the
The `jparse` parser, library and tools were co-developed by [Cody Boone
Ferguson](../authors.html#Cody_Boone_Ferguson) and [Landon Curt
Noll](http://www.isthe.com/chongo/index.html) in 2022-2025 and come from the
[jparse repo](https://github.com/xexyl/jparse). However, the **mkiocccentry
tools use a _clone_** of the [jparse repo](https://github.com/xexyl/jparse) **at
a _specific_ release**. Thus the `mkiocccentry` will at times be behind the
[jparse repo](https://github.com/xexyl/jparse)!
</p>
@@ -733,10 +742,8 @@ make sure that you're using the correct versions, which is also verified by
<p class="leftbar">
Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
for more details on `chkentry` and how you can use it to validate your
`.auth.json` and `.info.json` files (and your submission directory in general)
manually, without having to repackage your submission.
FAQ on "[validating your submission directory](../faq.html#chkentry)
for more details on `chkentry`.
</p>
<p class="leftbar">
@@ -1883,47 +1890,51 @@ We believe that Mark Twain's quote:
The IOCCC size tool source is not an original work, unless you are [Anthony C
Howe](../authors.html#Anthony_C_Howe), in which case it is original! :-)
Submitting source code that uses the content of
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c), unless you are
[Anthony C Howe](../authors.html#Anthony_C_Howe), might run the risk of
violating [Rule 7](rules.html#rule7).
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c),
_unless_ you are [Anthony C Howe](../authors.html#Anthony_C_Howe), might run the
risk of violating [Rule 7](rules.html#rule7).
</p>
<p class="leftbar"> The `txzchk(1)` tool source is not an original work,
<p class="leftbar"> The IOCCC submission tarball validator source is not an original work,
unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), in
which case it is original! :-) Submitting source code that uses the contents of
[txzchk.c](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c),
unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), might
_unless_ you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson), might
run the risk of violating [Rule 7](rules.html#rule7).</p>
<p class="leftbar">
Neither the [chkentry tool
source](https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c) nor
the [JSON parser and
library](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
nor
[jstrencode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c)
nor
In addition to the above tools, none of the [mkiocccentry
tools](https://github.com/ioccc-src/mkiocccentry), _including, **but not
limited**_ to
[mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/mkiocccentry.c),
[chkentry](https://github.com/ioccc-src/mkiocccentry/blob/master/chkentry.c),
[fnamchk](https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c)
and
[location](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/location_main.c),
nor the [JSON parser and
library](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md),
[jstrencode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrencode.c),
[jstrdecode](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jstrdecode.c)
nor any of the other [jparse
or any of the other [jparse
tools](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse)
(see the [jparse repo](https://github.com/xexyl/jparse/)), nor the [fnamchk tool
source](https://github.com/ioccc-src/mkiocccentry/blob/master/test_ioccc/fnamchk.c),
are original works,
(see the [jparse repo](https://github.com/xexyl/jparse/)), are original works,
unless you are [Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) or
[Landon Curt Noll](http://www.isthe.com/chongo/index.html), in which case they
are original! :-) Submitting source code that uses the code of any of these tools or
library, unless you are [Cody Boone
are original! :-) Submitting source code that uses the content of any of these tools or
library, _unless_ you are [Cody Boone
Ferguson](../authors.html#Cody_Boone_Ferguson) or [Landon Curt
Noll](http://www.isthe.com/chongo/index.html), might run the risk of violating
[Rule 7](rules.html#rule7).</p>
<p class="leftbar">
Unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html), the
remaining tools in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
are **NOT** original works. Submitting source code that uses the content of those tools,
unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html), might
run the risk of violating [Rule 7](rules.html#rule7).
</p>
And unless you are [Landon Curt Noll](http://www.isthe.com/chongo/index.html),
the code in
[dbg](https://github.com/ioccc-src/mkiocccentry/tree/master/dbg) and
[dyn_array](https://github.com/ioccc-src/mkiocccentry/tree/master/dyn_array) are
not original works. Submitting source code that uses the content of those
libraries, _unless_ you [Landon Curt
Noll](http://www.isthe.com/chongo/index.html), might run the risk of violating
[Rule 7](rules.html#rule7).</p>
<p class="leftbar">
[Rule 7](rules.html#rule7) does not prohibit you from writing your own
@@ -1940,7 +1951,7 @@ mind that writing an obfuscated version of a library runs the risk of violating
<p class="leftbar">
Even so, we do not recommend you try and submit a JSON parser due to
the fact it will likely exceed [the source code size limit](rules.html#rule2)
and because you likely can't beat [flex](https://github.com/westes/flex) or
and because you likely can't beat [flex](https://github.com/westes/flex) and
[bison](https://www.gnu.org/software/bison/) in obfuscation. This isn't to
say that [the so-called JSON spec](https://github.com/xexyl/jparse/blob/master/json_README.md#so-called-json-spec) is not
obfuscated, but unless you have some really clever way to compact and
quick-start.html
+29 -29
View File
@@ -424,6 +424,7 @@
<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
<!-- BEFORE: 1st line of markdown file: quick-start.md -->
<p>This is quick start guide is version <strong>28.0.0 2025-02-27</strong>.</p>
<div id="enter_questions">
<div id="enter">
<h1 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">Entering the IOCCC: the bare minimum you need to know</h1>
@@ -431,7 +432,7 @@
</div>
<p>To submit your code to the IOCCC, you <strong>MUST</strong> follow these steps:</p>
<div id="step_0">
<h4 id="verify-that-the-ioccc-is-pending-or-open-for-submissions">0. Verify that the IOCCC is pending or open for submissions</h4>
<h2 id="verify-that-the-ioccc-is-pending-or-open-for-submissions">0. Verify that the IOCCC is pending or open for submissions</h2>
</div>
<p>First, check the “<strong><a href="status.html">current status of the IOCCC</a></strong>” page to see current contest status.
You may <strong>only register for the IOCCC when the IOCCC is either <a href="status.html#pending">pending</a>
@@ -439,7 +440,7 @@ or <a href="status.html#open">open</a></strong>.</p>
<p>You may <strong>only submit your entries to the IOCCC when the IOCCC is <a href="status.html#open">open</a></strong>.</p>
<p>See also the <a href="news.html#news">IOCCC news</a> for more information.</p>
<div id="step_1">
<h4 id="read-the-latest-ioccc-rules-and-review-the-ioccc-guidelines">1. Read the latest IOCCC rules and review the IOCCC guidelines</h4>
<h2 id="read-the-latest-ioccc-rules-and-review-the-ioccc-guidelines">1. Read the latest IOCCC rules and review the IOCCC guidelines</h2>
</div>
<p>Please pay close attention to the <a href="next/rules.html">official IOCCC rules</a>.</p>
<p>You are also <strong>highly encouraged</strong> to review the
@@ -447,7 +448,7 @@ or <a href="status.html#open">open</a></strong>.</p>
suggestions, useful hints, and IOCCC humor. :-)</p>
<div id="step_2">
<div id="register">
<h4 id="register-for-the-ioccc">2. Register for the IOCCC</h4>
<h2 id="register-for-the-ioccc">2. Register for the IOCCC</h2>
</div>
</div>
<p><strong>IMPORTANT</strong>: You may <strong>only register for the IOCCC when the IOCCC is either <a href="status.html#pending">pending</a>
@@ -455,7 +456,7 @@ or <a href="status.html#open">open</a></strong>. See “<strong><a href="status.
<p>If the contest is <a href="status.html#pending">pending</a> or <a href="status.html#open">open</a>,
then follow the directions on “<strong><a href="next/register.html">how to register for the IOCCC</a></strong>”.</p>
<div id="step_3">
<h4 id="wait-for-your-submit-server-username-and-initial-password">3. Wait for your submit server username and initial password</h4>
<h2 id="wait-for-your-submit-server-username-and-initial-password">3. Wait for your submit server username and initial password</h2>
</div>
<p>Once you have <a href="next/register.html">registered for the IOCCC</a>,
and once the contest is <strong><a href="status.html#open">OPEN</a></strong>, one of the
@@ -477,7 +478,7 @@ password</strong>, and the <strong>CONTEST IS <a href="status.html#open">OPEN</a
have you checked your spam folder, <a href="contact.html">Contact the IOCCC</a>
for assistance.</p>
<div id="step_4">
<h4 id="login-to-the-submit-server-and-change-your-password">4. Login to the submit server and change your password</h4>
<h2 id="login-to-the-submit-server-and-change-your-password">4. Login to the submit server and change your password</h2>
</div>
<p>Using the <strong>Username</strong> and <strong>Initial password</strong> you receive via email in
<a href="#step_3">step 3</a>, you need to login to the <a href="https://submit.ioccc.org">IOCCC submit server</a>.</p>
@@ -487,7 +488,7 @@ from when one of the <a href="judges.html">IOCCC judges</a> sent that email.</p>
is only ready for submissions <strong>ONLY WHEN THE CONTEST IS <a href="status.html#open">open</a></strong>.</p>
<p>Please visit the “<strong><a href="next/pw-change.html">change your submit server initial password</a></strong>” page for detailed instructions.</p>
<div id="step_5">
<h4 id="obtain-and-compile-the-latest-mkiocccentry-toolkit">5. Obtain and compile the latest mkiocccentry toolkit</h4>
<h2 id="obtain-and-compile-the-latest-mkiocccentry-toolkit">5. Obtain and compile the latest mkiocccentry toolkit</h2>
</div>
<p>Once the contest is <a href="status.html#open">open</a>, download the most recent
version of the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry toolkit</a>.</p>
@@ -496,12 +497,14 @@ the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry toolkit</a>
could change. Once the content is <a href="status.html#open">open</a>, be sure
you <strong>have the latest</strong> version installed.</p>
<p>To help you, please see the
FAQ on “<a href="#obtaining_mkiocccentry">how to obtain the most recent mkiocccentry</a>”
FAQ on “<a href="faq.html#obtaining_mkiocccentry">how to obtain the most recent mkiocccentry</a>”,
the
FAQ on “<a href="faq.html#compiling_mkiocccentry">compiling mkiocccentry toolkit</a>”
and the
FAQ on “<a href="#compiling_mkiocccentry">compiling mkiocccentry toolkit</a>”,
FAQ on “<a href="faq.html#install">installing the mkiocccentry tools</a>”
for more details.</p>
<div id="step_6">
<h4 id="run-the-mkiocccentry-tool-to-form-your-submission-tarball">6. Run the mkiocccentry tool to form your submission tarball</h4>
<h2 id="run-the-mkiocccentry-tool-to-form-your-submission-tarball">6. Run the mkiocccentry tool to form your submission tarball</h2>
</div>
<p>For more details on <code>mkiocccentry</code>, what it is, how to obtain it and how to use
it, see the
@@ -525,7 +528,7 @@ guidelines</a>.</p>
<li><p><code>prog.c</code></p>
<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) as well
<p>Makefile to build (make all) and clean up (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
@@ -533,24 +536,6 @@ FAQ on “<a href="faq.html#remarks_md">remarks.md</a>”
for more info.</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
the tools from the top of the <code>mkiocccentry</code> repo directory just fine, though
you’ll have to use the form of <code>./mkiocccentry</code> instead of just <code>mkiocccentry</code>.
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><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). We recommend you install
the tools but if you wish to run it from the repo directory you may.</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
@@ -558,9 +543,24 @@ 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>
<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 (and we <strong>STRONGLY</strong> recommend you <strong>do</strong> install them),
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>. And remember to make sure you have
the latest version so you do not violate <a href="rules.html#rule17">Rule 17</a>.
See the
FAQ on “<a href="faq.html#obtaining_mkiocccentry">obtaining the latest mkiocccentry tools</a>”,
the
FAQ on “<a href="faq.html#compiling_mkiocccentry">compiling the mkiocccentry tools</a>”,
the
FAQ on “<a href="faq.html#installing">installing the mkiocccentry tools</a>”
and the
FAQ on “<a href="faq.html#using_mkiocccentry">using the mkiocccentry tools</a>”
for more help.</p>
<div id="step_7">
<div id="submit">
<h4 id="upload-your-submission-to-the-ioccc-submit-server">7. Upload your submission to the IOCCC submit server</h4>
<h2 id="upload-your-submission-to-the-ioccc-submit-server">7. Upload your submission to the IOCCC submit server</h2>
</div>
</div>
<p>The screenshots on the “<strong><a href="next/submit.html">how to upload your submission to the IOCCC</a></strong>” page
quick-start.md
+31 -31
View File
@@ -1,3 +1,5 @@
This is quick start guide is version **28.0.0 2025-02-27**.
<div id="enter_questions">
<div id="enter">
# Entering the IOCCC: the bare minimum you need to know
@@ -8,7 +10,7 @@ To submit your code to the IOCCC, you **MUST** follow these steps:
<div id="step_0">
#### 0. Verify that the IOCCC is pending or open for submissions
## 0. Verify that the IOCCC is pending or open for submissions
</div>
First, check the "**[current status of the IOCCC](status.html)**" page to see current contest status.
@@ -21,7 +23,7 @@ See also the [IOCCC news](news.html#news) for more information.
<div id="step_1">
#### 1. Read the latest IOCCC rules and review the IOCCC guidelines
## 1. Read the latest IOCCC rules and review the IOCCC guidelines
</div>
Please pay close attention to the [official IOCCC rules](next/rules.html).
@@ -33,7 +35,7 @@ suggestions, useful hints, and IOCCC humor. :-)
<div id="step_2">
<div id="register">
#### 2. Register for the IOCCC
## 2. Register for the IOCCC
</div>
</div>
@@ -45,7 +47,7 @@ then follow the directions on "**[how to register for the IOCCC](next/register.h
<div id="step_3">
#### 3. Wait for your submit server username and initial password
## 3. Wait for your submit server username and initial password
</div>
Once you have [registered for the IOCCC](next/register.html),
@@ -74,7 +76,7 @@ for assistance.
<div id="step_4">
#### 4. Login to the submit server and change your password
## 4. Login to the submit server and change your password
</div>
Using the **Username** and **Initial password** you receive via email in
@@ -90,7 +92,7 @@ Please visit the "**[change your submit server initial password](next/pw-change.
<div id="step_5">
#### 5. Obtain and compile the latest mkiocccentry toolkit
## 5. Obtain and compile the latest mkiocccentry toolkit
</div>
Once the contest is [open](status.html#open), download the most recent
@@ -102,14 +104,16 @@ could change. Once the content is [open](status.html#open), be sure
you **have the latest** version installed.
To help you, please see the
FAQ on "[how to obtain the most recent mkiocccentry](#obtaining_mkiocccentry)"
FAQ on "[how to obtain the most recent mkiocccentry](faq.html#obtaining_mkiocccentry)",
the
FAQ on "[compiling mkiocccentry toolkit](faq.html#compiling_mkiocccentry)"
and the
FAQ on "[compiling mkiocccentry toolkit](#compiling_mkiocccentry)",
FAQ on "[installing the mkiocccentry tools](faq.html#install)"
for more details.
<div id="step_6">
#### 6. Run the mkiocccentry tool to form your submission tarball
## 6. Run the mkiocccentry tool to form your submission tarball
</div>
For more details on `mkiocccentry`, what it is, how to obtain it and how to use
@@ -145,7 +149,7 @@ Three files are required to exist in `topdir`:
* `Makefile`
Makefile to build (make all) and cleanup (make clean & make clobber) as well
Makefile to build (make all) and clean up (make clean & make clobber) as well
as the other required rules
* `remarks.md`
@@ -156,26 +160,6 @@ Three files are required to exist in `topdir`:
**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
the tools from the top of the `mkiocccentry` repo directory just fine, though
you'll have to use the form of `./mkiocccentry` instead of just `mkiocccentry`.
However, installing it will make it easier for you as you can run it from your
submission's directory. See the
FAQ on "**[installing mkiocccentry](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#install)**"
at the mkiocccentry repo.
**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). We recommend you install
the tools but if you wish to run it from the repo directory you may.
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
@@ -186,10 +170,26 @@ for doing so in your `remarks.md` file.
See also [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 (and we **STRONGLY** recommend you **do** install them),
then you will have to specify the options for the tools that are required like
`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
the latest version so you do not violate [Rule 17](rules.html#rule17).
See the
FAQ on "[obtaining the latest mkiocccentry tools](faq.html#obtaining_mkiocccentry)",
the
FAQ on "[compiling the mkiocccentry tools](faq.html#compiling_mkiocccentry)",
the
FAQ on "[installing the mkiocccentry tools](faq.html#installing)"
and the
FAQ on "[using the mkiocccentry tools](faq.html#using_mkiocccentry)"
for more help.
<div id="step_7">
<div id="submit">
#### 7. Upload your submission to the IOCCC submit server
## 7. Upload your submission to the IOCCC submit server
</div>
</div>