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 --> <!-- BEFORE: 1st line of markdown file: faq.md -->
<h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1> <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> <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> <ul>
<li><strong>Q 0.0</strong>: <a class="normal" href="#submit">How can I enter the IOCCC?</a></li> <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 <p>We recommend starting with the <a href="next/Makefile.example">sample
Makefile</a> Makefile</a>
(renamed as <code>Makefile</code> of course) as a starting point for your (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 <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> rules and UNIX shell-style commands.</p>
<p>The first and default rule should be the <code>all</code> rule and should build your <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> </ul>
<p>Although the <code>mkiocccentry(1)</code> tool only checks for those rules, the most up to <p>Although the <code>mkiocccentry(1)</code> tool only checks for those rules, the most up to
date 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 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> <p>Jump to: <a href="#">top</a></p>
<div id="remarks_md"> <div id="remarks_md">
<div id="remarks"> <div id="remarks">
faq.md
+7 -4
View File
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents # 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) ## 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 We recommend starting with the [sample
Makefile](next/Makefile.example) Makefile](next/Makefile.example)
(renamed as `Makefile` of course) as a starting point for your (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 The `Makefile` is a file used by the `make(1)` command that contains
rules and UNIX shell-style commands. 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 Although the `mkiocccentry(1)` tool only checks for those rules, the most up to
date date
[Makefile.example](next/Makefile.example), `Makefile.example`
does have other rules like `everything` and `alt`, and we encourage you to use does have other rules like `everything` and `alt`, and we encourage you to use
that one. the one linked to above.
Jump to: [top](#) 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>” FAQ on “<a href="../faq.html#question">asking questions</a>”
about these guidelines. You might also find the about these guidelines. You might also find the
FAQ in general useful, especially 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> <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 <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 <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>
</div> </div>
<p class="leftbar"> <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>
<p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</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> <p>Jump to: <a href="#">top</a></p>
<div id="change_marks"> <div id="change_marks">
<h2 id="change-marks">Change marks</h2> <h1 id="change-marks">Change marks</h1>
</div> </div>
<p class="leftbar"> <p class="leftbar">
<strong>← Lines that start with this symbol indicate a change from the <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. <a href="../faq.html#size_rule2013-2020">2013-2020</a> IOCCC eras.
</p> </p>
<p>Jump to: <a href="#">top</a></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"> <p class="leftbar">
<a href="rules.html#rule17">Rule 17</a> (the <code>mkiocccentry(1)</code> rule) states that <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. 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> 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, <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 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>. page</a>.
<strong>PLEASE run the <code>bug_report.sh</code> script to help us out here!</strong> See the <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>”. FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p> </p>
<p class="leftbar"> <p class="leftbar">
If you want to know what <code>.auth.json</code> is, see the FAQ on If you want to know what <code>.auth.json</code> is, see the
“<a href="../faq.html#auth_json">.auth.json</a>”. If you want to know what the FAQ on “<a href="../faq.html#auth_json">.auth.json</a>”.
<code>.info.json</code> file is, see the FAQ on “<a href="../faq.html#info_json">.info.json</a>”. On If you want to know what the <code>.info.json</code> file is, see the
the other hand, if you want to know a bit more details about <code>chkentry</code>, 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>”. FAQ about “<a href="../faq.html#chkentry">chkentry</a>”.
</p> </p>
<p class="leftbar"> <p class="leftbar">
However, just because there are errors <strong>does not</strong> mean it is a bug in the However, even if <code>mkiocccentry</code> or one of the tools it invokes reports an error,
code. It might be an issue with your submission. Thus if you report an error as <strong>does not</strong> necessarily mean it is a bug in the code. It might be an issue with
a bug it might not be something that will be fixed as there might not be your submission. Thus if you report an error as a bug it might not be something
anything wrong. that will be fixed as there might not be anything wrong with the tools.
</p> </p>
<p class="leftbar"> <p class="leftbar">
On the other hand, some conditions are <strong>warnings</strong> and it allows you to 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"> <p class="leftbar">
See the See the
FAQ on “<a href="../faq.html#mkiocccentry">mkiocccentry</a>” FAQ on “<a href="../faq.html#mkiocccentry">mkiocccentry</a>”
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 <code>mkiocccentry(1)</code> will run.
</p> </p>
<div id="tools">
<h1 id="mkiocccentry-tools">mkiocccentry tools</h1>
</div>
<p class="leftbar"> <p class="leftbar">
The <code>mkiocccentry(1)</code> tool will execute a number of tools, some of which will 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 execute one or more additional tools.
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.
</p> </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> <h2 id="iocccsize"><code>iocccsize</code></h2>
<p class="leftbar"> <p class="leftbar">
<code>mkiocccentry(1)</code> will use code from <code>iocccsize(1)</code> which <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. 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>
<p class="leftbar"> <p class="leftbar">
In other words, you no longer need to run <code>iocccsize</code> manually. In other words, you no longer need to run <code>iocccsize</code> manually.
</p> </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> <p>Jump to: <a href="#">top</a></p>
<h2 id="chkentry"><code>chkentry</code></h2> <h2 id="chkentry"><code>chkentry</code></h2>
<p class="leftbar"> <p class="leftbar">
@@ -835,8 +801,8 @@ FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a
</p> </p>
<p class="leftbar"> <p class="leftbar">
Assuming that <code>chkentry(1)</code> successfully validates both <code>.auth.json</code> and 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 <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 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. <strong>NOT</strong> form a tarball if there are any issues.
</p> </p>
<p class="leftbar"> <p class="leftbar">
@@ -846,6 +812,43 @@ files, then unless it is a system specific problem, it is likely a bug in
unlikely. unlikely.
</p> </p>
<p class="leftbar"> <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 Please see the
FAQ on “<a href="../faq.html#chkentry">validating .auth.json and/or .info.json files</a> 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 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 <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 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 <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 page</a>. <strong>PLEASE run the
<code>bug_report.sh</code> script to help us out here!</strong> See 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>”. 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>
<p class="leftbar"> <p class="leftbar">
It is beyond the scope of this document to discuss the many tests that 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 code</a> or the man
page. You might find a fun option if you do either of these! page. You might find a fun option if you do either of these!
</p> </p>
@@ -894,10 +897,10 @@ FAQ on “<a href="../faq.html#txzchk">txzchk</a>”.
<p>Jump to: <a href="#">top</a></p> <p>Jump to: <a href="#">top</a></p>
<h2 id="fnamchk"><code>fnamchk</code></h2> <h2 id="fnamchk"><code>fnamchk</code></h2>
<p class="leftbar"> <p class="leftbar">
A tool that <a href="#txzchk">txzchk</a> runs is <code>fnamchk</code>. This is an important part of As an important part of its algorithm, <a href="#txzchk">txzchk</a> directly executes <code>fnamchk</code>.
its algorithm. If the filename is incorrect (or the filename does not match the 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 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. you wish to.
</p> </p>
<p class="leftbar"> <p class="leftbar">
@@ -906,19 +909,10 @@ tarball filename, see the
FAQ on “<a href="../faq.html#fnamchk">fnamchk</a>”. FAQ on “<a href="../faq.html#fnamchk">fnamchk</a>”.
</p> </p>
<p class="leftbar"> <p class="leftbar">
Note that the <code>txzchk(1)</code> tool uses <code>fnamchk(1)</code> tool as part of its algorithm. Because <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 <code>mkiocccentry(1)</code> does not directly invoke <code>fnamchk(1)</code>, although we will
in the judging process. in the judging process.
</p> </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"> <p class="leftbar">
It is extremely unlikely that <code>fnamchk(1)</code> reporting an invalid filename is a 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 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>”. FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>”.
</p> </p>
<p class="leftbar"> <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> </p>
<div id="bugs"> <div id="bugs">
<h1 id="problems-andor-bugs-in-tools">Problems and/or bugs in tools</h1> <h1 id="problems-andor-bugs-in-tools">Problems and/or bugs in tools</h1>
@@ -945,10 +945,10 @@ repo</a>.
</p> </p>
<p class="leftbar"> <p class="leftbar">
Of course, it is also possible for <code>mkiocccentry(1)</code>, or one or more of the 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 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 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! that’s OK too!
</p> </p>
<div id="make"> <div id="make">
@@ -972,10 +972,15 @@ download="Makefile">download example Makefile</a>
</p></li> </p></li>
</ul> </ul>
<p class="leftbar"> <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. needs.
</p> </p>
<p class="leftbar"> <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 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>. variant of the example <code>Makefile</code>, again renamed as <code>Makefile</code>.
</p> </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 We suggest that you compile your submission with a commonly available
<code>-std=gnu17</code> (ISO C 2017 with GNU extensions) C compiler. <code>-std=gnu17</code> (ISO C 2017 with GNU extensions) C compiler.
</p> </p>
<div id="cflags">
<div id="flags"> <div id="flags">
<h2 id="default-compiler-flags">Default compiler flags</h2> <h2 id="default-compiler-flags">Default compiler flags</h2>
</div> </div>
</div>
<p class="leftbar"> <p class="leftbar">
Unless you <strong>clearly state</strong> otherwise in your <code>remarks.md</code> file <strong>AND</strong> put in your Unless you <strong>clearly state</strong> otherwise in your <code>remarks.md</code> file, <strong>AND</strong> put in
submission’s <code>Makefile</code>, we <strong>will</strong> compile using <code>-std=gnu17 -O3 -g3</code>! your submission’s <code>Makefile</code>, we <strong>will</strong> compile using <code>-std=gnu17 -O3 -g3</code>!
</p> </p>
<p class="leftbar"> <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> 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 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 <code>remarks.md</code> file, <strong>AND</strong> adjust your <code>Makefile</code> accordingly.
</p> </p>
<p class="leftbar"> <p class="leftbar">
An example reason is that the optimiser is known to break some programs, but One reason that you might have to change the flags, is that the optimiser is
there are certainly other possible valid reasons. Again, just update the known to break some programs, but there are certainly other possible valid
<code>Makefile</code> and explain it in your <code>remarks.md</code>. 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> </p>
<div id="compilers"> <div id="compilers">
<h2 id="default-compiler">Default compiler</h2> <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> </p>
<pre><code> CSTD= -std=c17</code></pre> <pre><code> CSTD= -std=c17</code></pre>
<div id="opt"> <div id="opt">
<div id="optimization">
<div id="optimisation">
<div id="optimizer">
<div id="optimiser">
<h2 id="default-optimisation-level">Default optimisation level</h2> <h2 id="default-optimisation-level">Default optimisation level</h2>
</div> </div>
</div>
</div>
</div>
</div>
<p class="leftbar"> <p class="leftbar">
You may change the level of optimization and compiler debug level 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. 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> </p>
<pre><code> OPT= -O0 -g3</code></pre> <pre><code> OPT= -O0 -g3</code></pre>
<div id="warnings"> <div id="warnings">
<div id="cwarn">
<h2 id="compiler-warnings">Compiler warnings</h2> <h2 id="compiler-warnings">Compiler warnings</h2>
</div> </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"> <p class="leftbar">
For compilers, such as <code>clang</code>, that have the <code>-Weverything</code> option, 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 while you may wish to try it, you should read our
@@ -1046,9 +1079,14 @@ other version might!
<p class="leftbar"> <p class="leftbar">
On the other hand, if <code>${CC}</code> has “<code>clang</code>” in the name, the example <code>Makefile</code> will 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> 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> </p>
<h2 id="disabling-warnings">Disabling warnings</h2>
<p class="leftbar"> <p class="leftbar">
There is no real penalty for compiler warnings. Sometimes There is no real penalty for compiler warnings. Sometimes
compiler warnings cannot be helped: especially in the case of 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 On the other hand, some warnings cannot be disabled and are enabled by compilers
without any warning option specified. These are sometimes inevitable in without any warning option specified. These are sometimes inevitable in
obfuscated code and even in some non-obfuscated code, and you should not worry 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>
<p class="leftbar"> <p class="leftbar">
Some compilers like to warn about certain use of <code>char *</code>s which For instance, some compilers like to warn about use of <code>char *</code>s, which seems to
might not only be dubious itself, but it obviously can’t (always) be avoided, so you be dubious, as it obviously can’t (always) be avoided, being a big part of C, so
should not worry about this either; this is the warning 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 <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>” FAQ on “<a href="../faq.html#forced_warnings">forced warnings</a>”
and the and the
FAQ on “<a href="../faq.html#weverything">-Weverything</a>”. FAQ on “<a href="../faq.html#weverything">-Weverything</a>”.
</p> </p>
<h2 id="disabling-warnings">Disabling warnings</h2>
<p class="leftbar"> <p class="leftbar">
If you do have to disable warnings due to <code>-Weverything</code> automatically being If you do have to disable warnings due to <code>-Weverything</code> automatically being
included, you might wish to state this fact. :-) 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: try something such as:
</p> </p>
<pre><code> CSILENCE= -Wno-some-thing -Wno-another-thing</code></pre> <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> <pre><code> CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation</code></pre>
<p class="leftbar"> <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> <pre><code> CUNKNOWN=</code></pre>
<p>to:</p> <p class="leftbar">
to:
</p>
<pre><code> CUNKNOWN= -Wno-unknown-warning-option</code></pre> <pre><code> CUNKNOWN= -Wno-unknown-warning-option</code></pre>
<p class="leftbar"> <p class="leftbar">
Some compilers have reported this as an error, however, and if you have 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 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> </p>
<div id="macros"> <div id="macros">
<h2 id="defining-macros-in-the-makefile">Defining macros in the Makefile</h2> <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)" FAQ on "[asking questions](../faq.html#question)"
about these guidelines. You might also find the about these guidelines. You might also find the
FAQ in general useful, especially 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 # The IOCCC is closed
@@ -52,7 +54,7 @@ Jump to: [top](#)
</div> </div>
<p class="leftbar"> <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> </p>
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html). **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](#) Jump to: [top](#)
<div id="change_marks"> <div id="change_marks">
## Change marks # Change marks
</div> </div>
<p class="leftbar">**&larr; Lines that start with this symbol indicate a change from the <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. [2013-2020](../faq.html#size_rule2013-2020) IOCCC eras.
</p> </p>
Jump to: [top](#) Jump to: [top](#)
<div id="mkiocccentry"> <div id="mkiocccentry">
## `mkiocccentry` # `mkiocccentry`
</div> </div>
<p class="leftbar"> <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` below) fails to validate the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files that `mkiocccentry(1)` creates, [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 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). 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 **PLEASE run the `bug_report.sh` script to help us out here!** See the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)". FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p> </p>
<p class="leftbar"> <p class="leftbar">
If you want to know what `.auth.json` is, see the FAQ on If you want to know what `.auth.json` is, see the
"[.auth.json](../faq.html#auth_json)". If you want to know what the FAQ on "[.auth.json](../faq.html#auth_json)".
`.info.json` file is, see the FAQ on "[.info.json](../faq.html#info_json)". On If you want to know what the `.info.json` file is, see the
the other hand, if you want to know a bit more details about `chkentry`, 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)". FAQ about "[chkentry](../faq.html#chkentry)".
</p> </p>
<p class="leftbar"> <p class="leftbar">
However, just because there are errors **does not** mean it is a bug in the However, even if `mkiocccentry` or one of the tools it invokes reports an error,
code. It might be an issue with your submission. Thus if you report an error as **does not** necessarily mean it is a bug in the code. It might be an issue with
a bug it might not be something that will be fixed as there might not be your submission. Thus if you report an error as a bug it might not be something
anything wrong. that will be fixed as there might not be anything wrong with the tools.
</p> </p>
<p class="leftbar"> <p class="leftbar">
@@ -424,73 +426,32 @@ overwrites the file).
<p class="leftbar"> <p class="leftbar">
See the See the
FAQ on "[mkiocccentry](../faq.html#mkiocccentry)" 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>
<p class="leftbar">
Below are the tools that `mkiocccentry(1)` will run. <div id="tools">
</p> # mkiocccentry tools
</div>
<p class="leftbar"> <p class="leftbar">
The `mkiocccentry(1)` tool will execute a number of tools, some of which will 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 execute one or more additional tools.
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.
</p> </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"> <div id="iocccsize">
## `iocccsize` ## `iocccsize`
</div> </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. 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>
<p class="leftbar"> <p class="leftbar">
In other words, you no longer need to run `iocccsize` manually. In other words, you no longer need to run `iocccsize` manually.
</p> </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](#) Jump to: [top](#)
<div id="chkentry"> <div id="chkentry">
@@ -512,8 +473,8 @@ FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
<p class="leftbar"> <p class="leftbar">
Assuming that `chkentry(1)` successfully validates both `.auth.json` and Assuming that `chkentry(1)` successfully validates both `.auth.json` and
`.info.json` then the tarball will be formed and then `txzchk(1)` will be `.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 executed on it. In this case, there should be no problems, as `mkiocccentry(1)` should
**NOT** form a tarball if there are any issues. **NOT** form a tarball if there are any issues.
</p> </p>
@@ -524,6 +485,47 @@ files, then unless it is a system specific problem, it is likely a bug in
unlikely. unlikely.
</p> </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"> <p class="leftbar">
Please see the Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry) 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. for much more information on these files.
</p> </p>
Jump to: [top](#) Jump to: [top](#)
<div id="txzchk"> <div id="txzchk">
@@ -552,7 +553,7 @@ Jump to: [top](#)
compressed tarball; if any issues are found ('`feathers are stuck in the compressed tarball; if any issues are found ('`feathers are stuck in the
tarball`' :-) ) **AND if and _ONLY IF_ you used tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is **possibly** a bug in one of the tools and you `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 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 `bug_report.sh` script to help us out here!** See the
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)". 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"> <p class="leftbar">
It is beyond the scope of this document to discuss the many tests that 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 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! page. You might find a fun option if you do either of these!
</p> </p>
@@ -590,10 +591,10 @@ Jump to: [top](#)
</div> </div>
<p class="leftbar"> <p class="leftbar">
A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of As an important part of its algorithm, [txzchk](#txzchk) directly executes `fnamchk`.
its algorithm. If the filename is incorrect (or the filename does not match the 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 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. you wish to.
</p> </p>
@@ -604,22 +605,11 @@ FAQ on "[fnamchk](../faq.html#fnamchk)".
</p> </p>
<p class="leftbar"> <p class="leftbar">
Note that the `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm. Because `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm,
Thus `mkiocccentry(1)` does not directly invoke `fnamchk(1)`, although we will `mkiocccentry(1)` does not directly invoke `fnamchk(1)`, although we will
in the judging process. in the judging process.
</p> </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"> <p class="leftbar">
It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a 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 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>
<p class="leftbar"> <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> </p>
@@ -651,10 +647,10 @@ repo](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
<p class="leftbar"> <p class="leftbar">
Of course, it is also possible for `mkiocccentry(1)`, or one or more of the 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 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 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! that's OK too!
</p> </p>
@@ -677,10 +673,16 @@ Makefile](%%REPO_URL%%/next/Makefile.example)</p>
download="Makefile">download example Makefile</a></p> download="Makefile">download example Makefile</a></p>
<p class="leftbar"> <p class="leftbar">
Feel free to modify the `Makefile` to suit your obfuscated Feel free to modify the `Makefile` to suit your obfuscation
needs. needs.
</p> </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"> <p class="leftbar">
The rest of this section and its subsections will assume that you are using some The rest of this section and its subsections will assume that you are using some
variant of the example `Makefile`, again renamed as `Makefile`. 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. `-std=gnu17` (ISO C 2017 with GNU extensions) C compiler.
</p> </p>
<div id="cflags">
<div id="flags"> <div id="flags">
## Default compiler flags ## Default compiler flags
</div> </div>
</div>
<p class="leftbar"> <p class="leftbar">
Unless you **clearly state** otherwise in your `remarks.md` file **AND** put in your Unless you **clearly state** otherwise in your `remarks.md` file, **AND** put in
submission's `Makefile`, we **will** compile using `-std=gnu17 -O3 -g3`! your submission's `Makefile`, we **will** compile using `-std=gnu17 -O3 -g3`!
</p> </p>
<p class="leftbar"> <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** using the default `-std=gnu17 -O3 -g3` settings. Simply **explain why**
your submission should not be compiled using `-std=gnu17 -O3 -g3` in your submission should NOT be compiled using `-std=gnu17 -O3 -g3` in
your `remarks.md` file **and** adjust your `Makefile` accordingly. your `remarks.md` file, **AND** adjust your `Makefile` accordingly.
</p> </p>
<p class="leftbar"> <p class="leftbar">
An example reason is that the optimiser is known to break some programs, but One reason that you might have to change the flags, is that the optimiser is
there are certainly other possible valid reasons. Again, just update the known to break some programs, but there are certainly other possible valid
`Makefile` and explain it in your `remarks.md`. 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> </p>
<div id="compilers"> <div id="compilers">
@@ -745,13 +751,21 @@ by modifying the `CSTD` Makefile variable. For example, to use `c17` instead:
``` ```
<div id="opt"> <div id="opt">
<div id="optimization">
<div id="optimisation">
<div id="optimizer">
<div id="optimiser">
## Default optimisation level ## Default optimisation level
</div> </div>
</div>
</div>
</div>
</div>
<p class="leftbar"> <p class="leftbar">
You may change the level of optimization and compiler debug level You may change the level of optimization and compiler debug level
that your submission is compiled with, by modifying the `OPT` Makefile variable. 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> </p>
``` <!---make--> ``` <!---make-->
@@ -759,8 +773,30 @@ For example, to compile without optimization and with debug symbols:
``` ```
<div id="warnings"> <div id="warnings">
<div id="cwarn">
## Compiler warnings ## Compiler warnings
</div> </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"> <p class="leftbar">
For compilers, such as `clang`, that have the `-Weverything` option, For compilers, such as `clang`, that have the `-Weverything` option,
@@ -775,12 +811,15 @@ other version might!
<p class="leftbar"> <p class="leftbar">
On the other hand, if `${CC}` has "`clang`" in the name, the example `Makefile` will 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` 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> </p>
<div id="disabling-warnings"> <p class="leftbar">
## Disabling warnings If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further
</div> modified.
</p>
<p class="leftbar"> <p class="leftbar">
There is no real penalty for compiler warnings. Sometimes 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 On the other hand, some warnings cannot be disabled and are enabled by compilers
without any warning option specified. These are sometimes inevitable in without any warning option specified. These are sometimes inevitable in
obfuscated code and even in some non-obfuscated code, and you should not worry 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>
<p class="leftbar"> <p class="leftbar">
Some compilers like to warn about certain use of `char *`s which For instance, some compilers like to warn about use of `char *`s, which seems to
might not only be dubious itself, but it obviously can't (always) be avoided, so you be dubious, as it obviously can't (always) be avoided, being a big part of C, so
should not worry about this either; this is the warning 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 `-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)" FAQ on "[forced warnings](../faq.html#forced_warnings)"
and the and the
FAQ on "[-Weverything](../faq.html#weverything)". FAQ on "[-Weverything](../faq.html#weverything)".
</p> </p>
<div id="disabling-warnings">
## Disabling warnings
</div>
<p class="leftbar"> <p class="leftbar">
If you do have to disable warnings due to `-Weverything` automatically being 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 CSILENCE= -Wno-some-thing -Wno-another-thing
``` ```
<p class="leftbar">
For instance: For instance:
</p>
``` <!---make--> ``` <!---make-->
CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation
``` ```
<p class="leftbar"> <p class="leftbar">
If you do add "`-Wno-foo`" to your Makefile, consider changing: If you do add "`-Wno-foo`" to your Makefile, consider changing:
</p>
``` <!---make--> ``` <!---make-->
CUNKNOWN= CUNKNOWN=
``` ```
<p class="leftbar">
to: to:
</p>
``` <!---make--> ``` <!---make-->
CUNKNOWN= -Wno-unknown-warning-option CUNKNOWN= -Wno-unknown-warning-option
@@ -884,7 +930,8 @@ to:
<p class="leftbar"> <p class="leftbar">
Some compilers have reported this as an error, however, and if you have 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 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> </p>
<div id="macros"> <div id="macros">