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

Merge pull request #2763 from xexyl/guidelines-faq

Browse Source 
More corrections in FAQ and guidelines
This commit is contained in:
Landon Curt Noll authored and GitHub committed 2024-12-06 16:58:14 -08:00
2 parents 748a310691 e8448223d7
commit d5e53da02f
4 files changed
+314 -214
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+8 -4
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.1.6 2024-12-05</strong>.</p>
<p>This is FAQ version <strong>28.1.7 2024-12-06</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="#submit">How can I enter the IOCCC?</a></li>
@@ -791,7 +791,11 @@ or <a href="https://unix.org/online.html">later SUS</a>.</p>
<p>We recommend starting with the <a href="next/Makefile.example">sample
Makefile</a>
(renamed as <code>Makefile</code> of course) as a starting point for your
entry’s <code>Makefile</code>.</p>
entry’s <code>Makefile</code>:</p>
<ul>
<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/Makefile.example">view example Makefile</a></li>
<li><a href="next/Makefile.example">Makefile.example</a></li>
</ul>
<p>The <code>Makefile</code> is a file used by the <code>make(1)</code> command that contains
rules and UNIX shell-style commands.</p>
<p>The first and default rule should be the <code>all</code> rule and should build your
@@ -841,9 +845,9 @@ system, which we do like, you can have this rule invoke the script
</ul>
<p>Although the <code>mkiocccentry(1)</code> tool only checks for those rules, the most up to
date
<a href="next/Makefile.example">Makefile.example</a>,
<code>Makefile.example</code>
does have other rules like <code>everything</code> and <code>alt</code>, and we encourage you to use
that one.</p>
the one linked to above.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="remarks_md">
<div id="remarks">
faq.md
+7 -4
View File
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
This is FAQ version **28.1.6 2024-12-05**.
This is FAQ version **28.1.7 2024-12-06**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -462,7 +462,10 @@ Jump to: [top](#)
We recommend starting with the [sample
Makefile](next/Makefile.example)
(renamed as `Makefile` of course) as a starting point for your
entry's `Makefile`.
entry's `Makefile`:
- [view example Makefile](%%REPO_URL%%/next/Makefile.example)
- [Makefile.example](next/Makefile.example)
The `Makefile` is a file used by the `make(1)` command that contains
rules and UNIX shell-style commands.
@@ -513,9 +516,9 @@ The following rules should exist in your Makefile:
Although the `mkiocccentry(1)` tool only checks for those rules, the most up to
date
[Makefile.example](next/Makefile.example),
`Makefile.example`
does have other rules like `everything` and `alt`, and we encourage you to use
that one.
the one linked to above.
Jump to: [top](#)
next/guidelines.html
+143 -97
View File
@@ -437,7 +437,9 @@ as well as our
FAQ on “<a href="../faq.html#question">asking questions</a>”
about these guidelines. You might also find the
FAQ in general useful, especially the
<a href="../faq.html#submit">FAQ section “How to enter: the bare minimum you need to know”</a>.</p>
FAQ section “<a href="../faq.html#submit">How to enter: the bare minimum you need to know”</a>”
and the
FAQ section “<a href="../faq.html#submitting_help">Entering the IOCCC: more help and details</a>”.</p>
<h1 id="the-ioccc-is-closed">The IOCCC is closed</h1>
<p>The IOCCC is <strong>NOT</strong> accepting new submissions at this time. See the
<a href="../years.html">IOCCC winning entries page</a> for the entries that have won the
@@ -465,12 +467,12 @@ 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.25 2024-12-05</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.26 2024-12-06</strong>.
</p>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="change_marks">
<h2 id="change-marks">Change marks</h2>
<h1 id="change-marks">Change marks</h1>
</div>
<p class="leftbar">
<strong>← Lines that start with this symbol indicate a change from the
@@ -692,7 +694,7 @@ value similar to the <a href="../faq.html#size_rule2001-2012">2001-2012</a> and
<a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras.
</p>
<p>Jump to: <a href="#">top</a></p>
<h2 id="mkiocccentry"><code>mkiocccentry</code></h2>
<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
you <strong>MUST</strong> use the <code>mkiocccentry(1)</code> tool to package your submission tarball.
@@ -717,23 +719,24 @@ compressed tarball <strong>will not be formed</strong>. For instance, if <code>c
below) 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 that <code>mkiocccentry(1)</code> creates,
it is an error 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 issues
mkiocccentry bug report
page</a>.
<strong>PLEASE run the <code>bug_report.sh</code> script to help us out here!</strong> See the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the FAQ on
“<a href="../faq.html#auth_json">.auth.json</a>”. If you want to know what the
<code>.info.json</code> file is, see the FAQ on “<a href="../faq.html#info_json">.info.json</a>”. On
the other hand, if you want to know a bit more details about <code>chkentry</code>, see the
If you want to know what <code>.auth.json</code> is, see the
FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”.
If you want to know what the <code>.info.json</code> file is, see the
FAQ on “<a href="../faq.html#info_json">.info.json</a>”.
On the other hand, if you want to know a bit more details about <code>chkentry</code>, see the
FAQ about “<a href="../faq.html#chkentry">chkentry</a>”.
</p>
<p class="leftbar">
However, just because there are errors <strong>does not</strong> mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there might not be
anything wrong.
However, even if <code>mkiocccentry</code> or one of the tools it invokes reports an error,
<strong>does not</strong> necessarily mean it is a bug in the code. It might be an issue with
your submission. Thus if you report an error as a bug it might not be something
that will be fixed as there might not be anything wrong with the tools.
</p>
<p class="leftbar">
On the other hand, some conditions are <strong>warnings</strong> and it allows you to
@@ -765,60 +768,23 @@ overwrites the file).
<p class="leftbar">
See the
FAQ on “<a href="../faq.html#mkiocccentry">mkiocccentry</a>”
for how to use this tool in more detail.
</p>
<p class="leftbar">
Below are the tools that <code>mkiocccentry(1)</code> will run.
for how to use this tool, in more detail.
</p>
<div id="tools">
<h1 id="mkiocccentry-tools">mkiocccentry tools</h1>
</div>
<p class="leftbar">
The <code>mkiocccentry(1)</code> tool will execute a number of tools, some of which will
execute one or more additional tools; <code>chkentry(1)</code> will use the JSON parser
library <code>jparse(3)</code>; see the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">jparse
README.md</a>
in the <a href="https://github.com/ioccc-src/mkiocccentry/tree/master/jparse">mkiocccentry GitHub repo subdirectory
jparse</a> as well as
the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md">jparse library README.md
file</a>
in the <a href="https://github.com/ioccc-src/mkiocccentry/tree/master/jparse">mkiocccentry GitHub repo subdirectory
jparse</a>, for more
details.
execute one or more additional tools.
</p>
<p class="leftbar">
The original <code>jparse</code> code, co-developed by
<a href="http://www.isthe.com/chongo/index.html">Landon Curt Noll</a> and
<a href="../authors.html#Cody_Boone_Ferguson">Cody Boone Ferguson</a> in
2022, comes from the <a href="https://github.com/xexyl/jparse">jparse repo</a> <strong>but the
mkiocccentry tools use a <em>clone</em></strong> of this repo <strong>at a <em>specific</em> release</strong>.
Thus the <code>mkiocccentry</code> will at times be behind the <code>jparse</code> repo!
</p>
<p class="leftbar">
You do <strong>NOT need to install</strong> <code>jparse</code> from the <a href="https://github.com/xexyl/jparse">jparse
repo</a>! The <code>mkiocccentry</code> tools link in the
static library from the <code>mkiocccentry</code> clone. This also goes for the
<a href="https://github.com/lcn2/dbg">dbg</a> and
<a href="https://github.com/lcn2/dyn_array">dyn_array</a> libraries that the tools use.
</p>
<p class="leftbar">
In other words, <code>mkiocccentry</code> <strong>contains everything</strong> you need, and <em>even if you
do install</em> the libraries from their respective repos, it/they will <strong>not be
used</strong> when compiling the <code>mkiocccentry</code> tools.
</p>
<p>Jump to: <a href="#">top</a></p>
<h2 id="iocccsize"><code>iocccsize</code></h2>
<p class="leftbar">
<code>mkiocccentry(1)</code> will use code from <code>iocccsize(1)</code> which
detects a number of issues that you may ignore, if you wish, as described above.
As we already discussed how to invoke <code>mkiocccentry</code>, we will not include it
here again.
</p>
<p class="leftbar">
In other words, you no longer need to run <code>iocccsize</code> manually.
</p>
<p class="leftbar">
The <code>iocccsize</code> tool was originally part of a winning entry by <a href="../authors.html#Anthony_C_Howe">Anthony C
Howe</a>, but with some modifications over time, as
things have changed.
</p>
<p>Jump to: <a href="#">top</a></p>
<h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar">
@@ -835,8 +801,8 @@ 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. In this case, there should be no problems, as <code>mkiocccentry(1)</code> should
<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">
@@ -846,6 +812,43 @@ files, then unless it is a system specific problem, it is likely a bug in
unlikely.
</p>
<p class="leftbar">
<code>chkentry</code> uses the <code>jparse</code> library. See the
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md">jparse
README.md</a>
in the <a href="https://github.com/ioccc-src/mkiocccentry/tree/master/jparse">mkiocccentry GitHub repo subdirectory
jparse</a> as well as
the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md">jparse library README.md
file</a>
in the <a href="https://github.com/ioccc-src/mkiocccentry/tree/master/jparse">mkiocccentry GitHub repo subdirectory
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 comes
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">
You do <strong>NOT need to install</strong> <code>jparse</code> from the <a href="https://github.com/xexyl/jparse">jparse
repo</a>! The <code>mkiocccentry</code> tools link in the
static library from <code>mkiocccentry</code>’s clone itself. This also goes for the
<a href="https://github.com/lcn2/dbg">dbg</a> and
<a href="https://github.com/lcn2/dyn_array">dyn_array</a> libraries that the <code>mkiocccentry</code>
tools, the <code>dyn_array</code> library uses and the <code>jparse</code> library uses.
</p>
<p class="leftbar">
In other words, <code>mkiocccentry</code> <strong>contains everything</strong> you need, and <em>even if you
do install</em> the libraries from their respective repos, it/they will <strong>not be
used</strong> when compiling the <code>mkiocccentry</code> tools. This is important to
make sure that you’re using the correct versions, which is verified by
<code>chkentry</code>.
</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 this tool and how you can use it to validate your
@@ -865,7 +868,7 @@ for much more information on these files.
<code>txzchk(1)</code> performs a wide number of sanity checks on the xz
compressed tarball; if any issues are found (‘<code>feathers are stuck in the tarball</code>’ :-) ) <strong>AND if and <em>ONLY IF</em> you used
<code>mkiocccentry(1)</code></strong>, then it is <strong>possibly</strong> a bug in one of the tools and you
might want to <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
might want to <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 bug report
page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
@@ -878,7 +881,7 @@ and <a href="#fnamchk">fnamchk below</a> for more details on this tool.
</p>
<p class="leftbar">
It is beyond the scope of this document to discuss the many tests that
<code>txzchk(1)</code> do. In this case we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
<code>txzchk(1)</code> performs; if you wish to know, we refer you to the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c">source
code</a> or the man
page. You might find a fun option if you do either of these!
</p>
@@ -894,10 +897,10 @@ FAQ on “<a href="../faq.html#txzchk">txzchk</a>”.
<p>Jump to: <a href="#">top</a></p>
<h2 id="fnamchk"><code>fnamchk</code></h2>
<p class="leftbar">
A tool that <a href="#txzchk">txzchk</a> runs is <code>fnamchk</code>. This is an important part of
its algorithm. If the filename is incorrect (or the filename does not match the
As an important part of its algorithm, <a href="#txzchk">txzchk</a> directly executes <code>fnamchk</code>.
If the filename is invalid (or the filename does not match the
directory name of the tarball) then it is an <strong>error</strong> and you risk violating
<a href="rules.html#rule17">Rule 17</a>. Nevertheless, you can run the tool manually should
<a href="rules.html#rule17">Rule 17</a>. Nevertheless, you can run the tool manually, should
you wish to.
</p>
<p class="leftbar">
@@ -906,19 +909,10 @@ tarball filename, see the
FAQ on “<a href="../faq.html#fnamchk">fnamchk</a>”.
</p>
<p class="leftbar">
Note that the <code>txzchk(1)</code> tool uses <code>fnamchk(1)</code> tool as part of its algorithm.
Thus <code>mkiocccentry(1)</code> does not directly invoke <code>fnamchk(1)</code>, although we will
Because <code>txzchk(1)</code> tool uses <code>fnamchk(1)</code> tool as part of its algorithm,
<code>mkiocccentry(1)</code> does not directly invoke <code>fnamchk(1)</code>, although we will
in the judging process.
</p>
<hr>
<p class="leftbar">
At the risk of stating the obvious: you run <strong>a VERY BIG risk</strong> of having
your submission rejected if you package your own tarball and there are <strong>ANY
problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
everything checks out OK you should <strong>NOT</strong> assume that everything <strong>IS</strong> OK.
</p>
<p class="leftbar">
It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a
bug in <code>fnamchk(1)</code> and as such, ignoring such an issue risks violating <a href="rules.html#rule17">Rule
@@ -931,7 +925,13 @@ See the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>.
As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>, and at
the risk of stating the obvious, you run <strong>a VERY BIG risk</strong> of having
your submission rejected if you package your own tarball, and there are <strong>ANY
problems</strong>. For instance, if <code>chkentry(1)</code> found a problem in your <code>.info.json</code>
file, the <code>mkiocccentry(1)</code> tool would not package it. But if you were to package
it manually, you would be violating <a href="rules.html#rule17">Rule 17</a>. But even if
everything checks out OK you should <strong>NOT</strong> assume that everything <strong>IS</strong> OK.
</p>
<div id="bugs">
<h1 id="problems-andor-bugs-in-tools">Problems and/or bugs in tools</h1>
@@ -945,10 +945,10 @@ repo</a>.
</p>
<p class="leftbar">
Of course, it is also possible for <code>mkiocccentry(1)</code>, or one or more of the
tools it executes (or another tool executes), to fail, and <strong>NOT</strong> because of a
tools it executes (or another tool executes), to fail, but <strong>NOT</strong> because of a
bug. An example problem is if there is not enough memory available or if some
other library or syscall fails. Nonetheless it might be worth reporting as a
bug; it is a judgement call; if it’s a bug it’ll be addressed and if it’s not
bug; it is a judgement call: if it’s a bug it’ll be addressed and if it’s not
that’s OK too!
</p>
<div id="make">
@@ -972,10 +972,15 @@ download="Makefile">download example Makefile</a>
</p></li>
</ul>
<p class="leftbar">
Feel free to modify the <code>Makefile</code> to suit your obfuscated
Feel free to modify the <code>Makefile</code> to suit your obfuscation
needs.
</p>
<p class="leftbar">
Please add a space between the <code>=</code> and the value of variables, in the
<code>Makefile</code>, making sure that the <code>=</code> comes immediately after the name. See the
example <code>Makefile</code> for examples.
</p>
<p class="leftbar">
The rest of this section and its subsections will assume that you are using some
variant of the example <code>Makefile</code>, again renamed as <code>Makefile</code>.
</p>
@@ -983,23 +988,27 @@ variant of the example <code>Makefile</code>, again renamed as <code>Makefile</c
We suggest that you compile your submission with a commonly available
<code>-std=gnu17</code> (ISO C 2017 with GNU extensions) C compiler.
</p>
<div id="cflags">
<div id="flags">
<h2 id="default-compiler-flags">Default compiler flags</h2>
</div>
</div>
<p class="leftbar">
Unless you <strong>clearly state</strong> otherwise in your <code>remarks.md</code> file <strong>AND</strong> put in your
submission’s <code>Makefile</code>, we <strong>will</strong> compile using <code>-std=gnu17 -O3 -g3</code>!
Unless you <strong>clearly state</strong> otherwise in your <code>remarks.md</code> file, <strong>AND</strong> put in
your submission’s <code>Makefile</code>, we <strong>will</strong> compile using <code>-std=gnu17 -O3 -g3</code>!
</p>
<p class="leftbar">
It <strong>is OK</strong> if you need to require your submission to <strong>not be</strong> compiled
It <strong>is OK</strong> if you need to require your submission to <strong>NOT be</strong> compiled
using the default <code>-std=gnu17 -O3 -g3</code> settings. Simply <strong>explain why</strong>
your submission should not be compiled using <code>-std=gnu17 -O3 -g3</code> in
your <code>remarks.md</code> file <strong>and</strong> adjust your <code>Makefile</code> accordingly.
your submission should NOT be compiled using <code>-std=gnu17 -O3 -g3</code> in
your <code>remarks.md</code> file, <strong>AND</strong> adjust your <code>Makefile</code> accordingly.
</p>
<p class="leftbar">
An example reason is that the optimiser is known to break some programs, but
there are certainly other possible valid reasons. Again, just update the
<code>Makefile</code> and explain it in your <code>remarks.md</code>.
One reason that you might have to change the flags, is that the optimiser is
known to break some programs, but there are certainly other possible valid
reasons. Again, just update the <code>Makefile</code> and explain it in your <code>remarks.md</code>.
See the <a href="#optimiser">optimiser section</a> for details for changing optimiser
flags.
</p>
<div id="compilers">
<h2 id="default-compiler">Default compiler</h2>
@@ -1023,17 +1032,41 @@ by modifying the <code>CSTD</code> Makefile variable. For example, to use <code>
</p>
<pre><code> CSTD= -std=c17</code></pre>
<div id="opt">
<div id="optimization">
<div id="optimisation">
<div id="optimizer">
<div id="optimiser">
<h2 id="default-optimisation-level">Default optimisation level</h2>
</div>
</div>
</div>
</div>
</div>
<p class="leftbar">
You may change the level of optimization and compiler debug level
that your submission is compiled with, by modifying the <code>OPT</code> Makefile variable.
For example, to compile without optimization and with debug symbols:
For example, to compile without optimization, and to include debug symbols:
</p>
<pre><code> OPT= -O0 -g3</code></pre>
<div id="warnings">
<div id="cwarn">
<h2 id="compiler-warnings">Compiler warnings</h2>
</div>
</div>
<p class="leftbar">
The default warning flags are set via the <code>CWARN</code> variable, as shown in the
example <code>Makefile</code>:
</p>
<pre><code> # Common C compiler warning flags
#
CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN}</code></pre>
<p class="leftbar">
For details on <code>CSILENCE</code> and <code>CUNKNOWN</code>, see the <a href="#disabling-warnings">section on disabling
warnings</a>.
</p>
<div id="weverything">
<h3 id="the--weverything-option">The <code>-Weverything</code> option</h3>
</div>
<p class="leftbar">
For compilers, such as <code>clang</code>, that have the <code>-Weverything</code> option,
while you may wish to try it, you should read our
@@ -1046,9 +1079,14 @@ other version might!
<p class="leftbar">
On the other hand, if <code>${CC}</code> has “<code>clang</code>” in the name, the example <code>Makefile</code> will
automatically enable <code>-Weverything</code>, so you might have to use <code>-Wno-foo</code>
options, as detailed below.
options anyway, as detailed below. See the
FAQ on “<a href="../faq.html#weverything">-Weverything</a>”
for more details.
</p>
<p class="leftbar">
If “<code>clang</code>” is NOT in <code>${CC}</code>, the <code>CWARN</code> variable will not be further
modified.
</p>
<h2 id="disabling-warnings">Disabling warnings</h2>
<p class="leftbar">
There is no real penalty for compiler warnings. Sometimes
compiler warnings cannot be helped: especially in the case of
@@ -1078,17 +1116,19 @@ not meeting your claims).
On the other hand, some warnings cannot be disabled and are enabled by compilers
without any warning option specified. These are sometimes inevitable in
obfuscated code and even in some non-obfuscated code, and you should not worry
about this, though it might be worth pointing out (see below for an example).
about this, though it might be worth pointing out.
</p>
<p class="leftbar">
Some compilers like to warn about certain use of <code>char *</code>s which
might not only be dubious itself, but it obviously can’t (always) be avoided, so you
should not worry about this either; this is the warning
<code>-Wunsafe-buffer-usage</code> and the way to disable it is <code>-Wno-unsafe-buffer-usage</code>. See also the
For instance, some compilers like to warn about use of <code>char *</code>s, which seems to
be dubious, as it obviously can’t (always) be avoided, being a big part of C, so
you should not worry about this either; this is the warning
<code>-Wunsafe-buffer-usage</code> and the way to disable it is <code>-Wno-unsafe-buffer-usage</code>.
See also the
FAQ on “<a href="../faq.html#forced_warnings">forced warnings</a>”
and the
FAQ on “<a href="../faq.html#weverything">-Weverything</a>”.
</p>
<h2 id="disabling-warnings">Disabling warnings</h2>
<p class="leftbar">
If you do have to disable warnings due to <code>-Weverything</code> automatically being
included, you might wish to state this fact. :-)
@@ -1110,17 +1150,23 @@ To turn off a compiler warning, in your submission’s <code>Makefile</code>,
try something such as:
</p>
<pre><code> CSILENCE= -Wno-some-thing -Wno-another-thing</code></pre>
<p>For instance:</p>
<p class="leftbar">
For instance:
</p>
<pre><code> CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation</code></pre>
<p class="leftbar">
<p>If you do add “<code>-Wno-foo</code>” to your Makefile, consider changing:</p>
If you do add “<code>-Wno-foo</code>” to your Makefile, consider changing:
</p>
<pre><code> CUNKNOWN=</code></pre>
<p>to:</p>
<p class="leftbar">
to:
</p>
<pre><code> CUNKNOWN= -Wno-unknown-warning-option</code></pre>
<p class="leftbar">
Some compilers have reported this as an error, however, and if you have
such a compiler you might want to not add it, or at least note in your
<code>remarks.md</code> the OS, OS version and compiler that this shows up.
<code>remarks.md</code> which OS, OS version, compiler and compiler version you had the
problem.
</p>
<div id="macros">
<h2 id="defining-macros-in-the-makefile">Defining macros in the Makefile</h2>
next/guidelines.md
+156 -109
View File
@@ -14,7 +14,9 @@ as well as our
FAQ on "[asking questions](../faq.html#question)"
about these guidelines. You might also find the
FAQ in general useful, especially the
[FAQ section "How to enter: the bare minimum you need to know"](../faq.html#submit).
FAQ section "[How to enter: the bare minimum you need to know"](../faq.html#submit)"
and the
FAQ section "[Entering the IOCCC: more help and details](../faq.html#submitting_help)".
# The IOCCC is closed
@@ -52,7 +54,7 @@ Jump to: [top](#)
</div>
<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-05**.
These [IOCCC guidelines](guidelines.html) are version **28.26 2024-12-06**.
</p>
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -60,7 +62,7 @@ These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-05**.
Jump to: [top](#)
<div id="change_marks">
## Change marks
# Change marks
</div>
<p class="leftbar">**&larr; Lines that start with this symbol indicate a change from the
@@ -329,11 +331,10 @@ value similar to the [2001-2012](../faq.html#size_rule2001-2012) and
[2013-2020](../faq.html#size_rule2013-2020) IOCCC eras.
</p>
Jump to: [top](#)
<div id="mkiocccentry">
## `mkiocccentry`
# `mkiocccentry`
</div>
<p class="leftbar">
@@ -364,25 +365,26 @@ compressed tarball **will not be formed**. For instance, if `chkentry(1)` (see
below) fails to validate the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files that `mkiocccentry(1)` creates,
it is an error and **possibly** a bug that you should [report as a bug at the
mkiocccentry issues
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).
**PLEASE run the `bug_report.sh` script to help us out here!** See the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
<p class="leftbar">
If you want to know what `.auth.json` is, see the FAQ on
"[.auth.json](../faq.html#auth_json)". If you want to know what the
`.info.json` file is, see the FAQ on "[.info.json](../faq.html#info_json)". On
the other hand, if you want to know a bit more details about `chkentry`, see the
If you want to know what `.auth.json` is, see the
FAQ on "[.auth.json](../faq.html#auth_json)".
If you want to know what the `.info.json` file is, see the
FAQ on "[.info.json](../faq.html#info_json)".
On the other hand, if you want to know a bit more details about `chkentry`, see the
FAQ about "[chkentry](../faq.html#chkentry)".
</p>
<p class="leftbar">
However, just because there are errors **does not** mean it is a bug in the
code. It might be an issue with your submission. Thus if you report an error as
a bug it might not be something that will be fixed as there might not be
anything wrong.
However, even if `mkiocccentry` or one of the tools it invokes reports an error,
**does not** necessarily mean it is a bug in the code. It might be an issue with
your submission. Thus if you report an error as a bug it might not be something
that will be fixed as there might not be anything wrong with the tools.
</p>
<p class="leftbar">
@@ -424,73 +426,32 @@ overwrites the file).
<p class="leftbar">
See the
FAQ on "[mkiocccentry](../faq.html#mkiocccentry)"
for how to use this tool in more detail.
for how to use this tool, in more detail.
</p>
<p class="leftbar">
Below are the tools that `mkiocccentry(1)` will run.
</p>
<div id="tools">
# mkiocccentry tools
</div>
<p class="leftbar">
The `mkiocccentry(1)` tool will execute a number of tools, some of which will
execute one or more additional tools; `chkentry(1)` will use the JSON parser
library `jparse(3)`; see the [jparse
README.md](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
in the [mkiocccentry GitHub repo subdirectory
jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse) as well as
the [jparse library README.md
file](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md)
in the [mkiocccentry GitHub repo subdirectory
jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse), for more
details.
execute one or more additional tools.
</p>
<p class="leftbar">
The original `jparse` code, co-developed by
[Landon Curt Noll](http://www.isthe.com/chongo/index.html) and
[Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) in
2022, comes from the [jparse repo](https://github.com/xexyl/jparse) **but the
mkiocccentry tools use a _clone_** of this repo **at a _specific_ release**.
Thus the `mkiocccentry` will at times be behind the `jparse` repo!
</p>
<p class="leftbar">
You do **NOT need to install** `jparse` from the [jparse
repo](https://github.com/xexyl/jparse)! The `mkiocccentry` tools link in the
static library from the `mkiocccentry` clone. This also goes for the
[dbg](https://github.com/lcn2/dbg) and
[dyn_array](https://github.com/lcn2/dyn_array) libraries that the tools use.
</p>
<p class="leftbar">
In other words, `mkiocccentry` **contains everything** you need, and _even if you
do install_ the libraries from their respective repos, it/they will **not be
used** when compiling the `mkiocccentry` tools.
</p>
Jump to: [top](#)
<div id="iocccsize">
## `iocccsize`
</div>
<p class="leftbar">`mkiocccentry(1)` will use code from `iocccsize(1)` which
<p class="leftbar">
`mkiocccentry(1)` will use code from `iocccsize(1)` which
detects a number of issues that you may ignore, if you wish, as described above.
As we already discussed how to invoke `mkiocccentry`, we will not include it
here again.
</p>
<p class="leftbar">
In other words, you no longer need to run `iocccsize` manually.
</p>
<p class="leftbar">
The `iocccsize` tool was originally part of a winning entry by [Anthony C
Howe](../authors.html#Anthony_C_Howe), but with some modifications over time, as
things have changed.
</p>
Jump to: [top](#)
<div id="chkentry">
@@ -512,8 +473,8 @@ FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
<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. In this case, there should be no problems, as `mkiocccentry(1)` should
`.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>
@@ -524,6 +485,47 @@ files, then unless it is a system specific problem, it is likely a bug in
unlikely.
</p>
<p class="leftbar">
`chkentry` uses the `jparse` library. See the
[jparse
README.md](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
in the [mkiocccentry GitHub repo subdirectory
jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse) as well as
the [jparse library README.md
file](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md)
in the [mkiocccentry GitHub repo subdirectory
jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse), for more
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 comes
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>
<p class="leftbar">
You do **NOT need to install** `jparse` from the [jparse
repo](https://github.com/xexyl/jparse)! The `mkiocccentry` tools link in the
static library from `mkiocccentry`'s clone itself. This also goes for the
[dbg](https://github.com/lcn2/dbg) and
[dyn_array](https://github.com/lcn2/dyn_array) libraries that the `mkiocccentry`
tools, the `dyn_array` library uses and the `jparse` library uses.
</p>
<p class="leftbar">
In other words, `mkiocccentry` **contains everything** you need, and _even if you
do install_ the libraries from their respective repos, it/they will **not be
used** when compiling the `mkiocccentry` tools. This is important to
make sure that you're using the correct versions, which is verified by
`chkentry`.
</p>
<p class="leftbar">
Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
@@ -540,7 +542,6 @@ FAQ on "[.info.json](../faq.html#info_json)"
for much more information on these files.
</p>
Jump to: [top](#)
<div id="txzchk">
@@ -552,7 +553,7 @@ Jump to: [top](#)
compressed tarball; if any issues are found ('`feathers are stuck in the
tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is **possibly** a bug in one of the tools and you
might want to [report it as a bug at the mkiocccentry issues
might want to [report it 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). **PLEASE run the
`bug_report.sh` script to help us out here!** See the
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
@@ -567,7 +568,7 @@ and [fnamchk below](#fnamchk) for more details on this tool.
<p class="leftbar">
It is beyond the scope of this document to discuss the many tests that
`txzchk(1)` do. In this case we refer you to the [source
`txzchk(1)` performs; if you wish to know, we refer you to the [source
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c) or the man
page. You might find a fun option if you do either of these!
</p>
@@ -590,10 +591,10 @@ Jump to: [top](#)
</div>
<p class="leftbar">
A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of
its algorithm. If the filename is incorrect (or the filename does not match the
As an important part of its algorithm, [txzchk](#txzchk) directly executes `fnamchk`.
If the filename is invalid (or the filename does not match the
directory name of the tarball) then it is an **error** and you risk violating
[Rule 17](rules.html#rule17). Nevertheless, you can run the tool manually should
[Rule 17](rules.html#rule17). Nevertheless, you can run the tool manually, should
you wish to.
</p>
@@ -604,22 +605,11 @@ FAQ on "[fnamchk](../faq.html#fnamchk)".
</p>
<p class="leftbar">
Note that the `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm.
Thus `mkiocccentry(1)` does not directly invoke `fnamchk(1)`, although we will
Because `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm,
`mkiocccentry(1)` does not directly invoke `fnamchk(1)`, although we will
in the judging process.
</p>
<hr>
<p class="leftbar">
At the risk of stating the obvious: you run **a VERY BIG risk** of having
your submission rejected if you package your own tarball and there are **ANY
problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
file, the `mkiocccentry(1)` tool would not package it. But if you were to package
it manually, you would be violating [Rule 17](rules.html#rule17). But even if
everything checks out OK you should **NOT** assume that everything **IS** OK.
</p>
<p class="leftbar">
It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a
bug in `fnamchk(1)` and as such, ignoring such an issue risks violating [Rule
@@ -633,7 +623,13 @@ FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
<p class="leftbar">
As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**, and at
the risk of stating the obvious, you run **a VERY BIG risk** of having
your submission rejected if you package your own tarball, and there are **ANY
problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
file, the `mkiocccentry(1)` tool would not package it. But if you were to package
it manually, you would be violating [Rule 17](rules.html#rule17). But even if
everything checks out OK you should **NOT** assume that everything **IS** OK.
</p>
@@ -651,10 +647,10 @@ repo](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
<p class="leftbar">
Of course, it is also possible for `mkiocccentry(1)`, or one or more of the
tools it executes (or another tool executes), to fail, and **NOT** because of a
tools it executes (or another tool executes), to fail, but **NOT** because of a
bug. An example problem is if there is not enough memory available or if some
other library or syscall fails. Nonetheless it might be worth reporting as a
bug; it is a judgement call; if it's a bug it'll be addressed and if it's not
bug; it is a judgement call: if it's a bug it'll be addressed and if it's not
that's OK too!
</p>
@@ -677,10 +673,16 @@ Makefile](%%REPO_URL%%/next/Makefile.example)</p>
download="Makefile">download example Makefile</a></p>
<p class="leftbar">
Feel free to modify the `Makefile` to suit your obfuscated
Feel free to modify the `Makefile` to suit your obfuscation
needs.
</p>
<p class="leftbar">
Please add a space between the `=` and the value of variables, in the
`Makefile`, making sure that the `=` comes immediately after the name. See the
example `Makefile` for examples.
</p>
<p class="leftbar">
The rest of this section and its subsections will assume that you are using some
variant of the example `Makefile`, again renamed as `Makefile`.
@@ -691,26 +693,30 @@ We suggest that you compile your submission with a commonly available
`-std=gnu17` (ISO C 2017 with GNU extensions) C compiler.
</p>
<div id="cflags">
<div id="flags">
## Default compiler flags
</div>
</div>
<p class="leftbar">
Unless you **clearly state** otherwise in your `remarks.md` file **AND** put in your
submission's `Makefile`, we **will** compile using `-std=gnu17 -O3 -g3`!
Unless you **clearly state** otherwise in your `remarks.md` file, **AND** put in
your submission's `Makefile`, we **will** compile using `-std=gnu17 -O3 -g3`!
</p>
<p class="leftbar">
It **is OK** if you need to require your submission to **not be** compiled
It **is OK** if you need to require your submission to **NOT be** compiled
using the default `-std=gnu17 -O3 -g3` settings. Simply **explain why**
your submission should not be compiled using `-std=gnu17 -O3 -g3` in
your `remarks.md` file **and** adjust your `Makefile` accordingly.
your submission should NOT be compiled using `-std=gnu17 -O3 -g3` in
your `remarks.md` file, **AND** adjust your `Makefile` accordingly.
</p>
<p class="leftbar">
An example reason is that the optimiser is known to break some programs, but
there are certainly other possible valid reasons. Again, just update the
`Makefile` and explain it in your `remarks.md`.
One reason that you might have to change the flags, is that the optimiser is
known to break some programs, but there are certainly other possible valid
reasons. Again, just update the `Makefile` and explain it in your `remarks.md`.
See the [optimiser section](#optimiser) for details for changing optimiser
flags.
</p>
<div id="compilers">
@@ -745,13 +751,21 @@ by modifying the `CSTD` Makefile variable. For example, to use `c17` instead:
```
<div id="opt">
<div id="optimization">
<div id="optimisation">
<div id="optimizer">
<div id="optimiser">
## Default optimisation level
</div>
</div>
</div>
</div>
</div>
<p class="leftbar">
You may change the level of optimization and compiler debug level
that your submission is compiled with, by modifying the `OPT` Makefile variable.
For example, to compile without optimization and with debug symbols:
For example, to compile without optimization, and to include debug symbols:
</p>
``` <!---make-->
@@ -759,8 +773,30 @@ For example, to compile without optimization and with debug symbols:
```
<div id="warnings">
<div id="cwarn">
## Compiler warnings
</div>
</div>
<p class="leftbar">
The default warning flags are set via the `CWARN` variable, as shown in the
example `Makefile`:
</p>
``` <!---sh-->
# Common C compiler warning flags
#
CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN}
```
<p class="leftbar">
For details on `CSILENCE` and `CUNKNOWN`, see the [section on disabling
warnings](#disabling-warnings).
</p>
<div id="weverything">
### The `-Weverything` option
</div>
<p class="leftbar">
For compilers, such as `clang`, that have the `-Weverything` option,
@@ -775,12 +811,15 @@ other version might!
<p class="leftbar">
On the other hand, if `${CC}` has "`clang`" in the name, the example `Makefile` will
automatically enable `-Weverything`, so you might have to use `-Wno-foo`
options, as detailed below.
options anyway, as detailed below. See the
FAQ on "[-Weverything](../faq.html#weverything)"
for more details.
</p>
<div id="disabling-warnings">
## Disabling warnings
</div>
<p class="leftbar">
If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further
modified.
</p>
<p class="leftbar">
There is no real penalty for compiler warnings. Sometimes
@@ -818,19 +857,23 @@ not meeting your claims).
On the other hand, some warnings cannot be disabled and are enabled by compilers
without any warning option specified. These are sometimes inevitable in
obfuscated code and even in some non-obfuscated code, and you should not worry
about this, though it might be worth pointing out (see below for an example).
about this, though it might be worth pointing out.
</p>
<p class="leftbar">
Some compilers like to warn about certain use of `char *`s which
might not only be dubious itself, but it obviously can't (always) be avoided, so you
should not worry about this either; this is the warning
`-Wunsafe-buffer-usage` and the way to disable it is `-Wno-unsafe-buffer-usage`. See also the
For instance, some compilers like to warn about use of `char *`s, which seems to
be dubious, as it obviously can't (always) be avoided, being a big part of C, so
you should not worry about this either; this is the warning
`-Wunsafe-buffer-usage` and the way to disable it is `-Wno-unsafe-buffer-usage`.
See also the
FAQ on "[forced warnings](../faq.html#forced_warnings)"
and the
FAQ on "[-Weverything](../faq.html#weverything)".
</p>
<div id="disabling-warnings">
## Disabling warnings
</div>
<p class="leftbar">
If you do have to disable warnings due to `-Weverything` automatically being
@@ -860,22 +903,25 @@ try something such as:
CSILENCE= -Wno-some-thing -Wno-another-thing
```
<p class="leftbar">
For instance:
</p>
``` <!---make-->
CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation
```
<p class="leftbar">
If you do add "`-Wno-foo`" to your Makefile, consider changing:
</p>
``` <!---make-->
CUNKNOWN=
```
<p class="leftbar">
to:
</p>
``` <!---make-->
CUNKNOWN= -Wno-unknown-warning-option
@@ -884,7 +930,8 @@ to:
<p class="leftbar">
Some compilers have reported this as an error, however, and if you have
such a compiler you might want to not add it, or at least note in your
`remarks.md` the OS, OS version and compiler that this shows up.
`remarks.md` which OS, OS version, compiler and compiler version you had the
problem.
</p>
<div id="macros">