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

Add better link system for try / Makefile.example

Browse Source 
The guidelines now link to both GitHub (viewing option) and directly to
the files Makefile.example, try.sh and try.alt.sh, as does the FAQ.

I made sure to keep the version of the guidelines and rules the same (as
in major.minor) but updated the date, as these changes are part of the
previous commit.
This commit is contained in:
Cody Boone Ferguson committed 2024-12-05 10:06:14 -08:00
1 parent 154d40710b
commit 2f4fe82068
6 files changed
+346 -145
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

faq.html
+19 -11
View File
@@ -892,10 +892,15 @@ this is not clear!</li>
</div>
<p>If your submission has more than one use, or if you have interesting ways to
invoke your program, perhaps using other commonly installed tools (or tools
included in your submission), it can be helpful to include a <code>try.sh</code> script.</p>
<p>A <a href="next/try.sh">template try.sh</a> can be used as a
starting point, or you can look at some of the others in the website, to get
some ideas.</p>
included in your submission), it can be helpful to include a <code>try.sh</code> script:</p>
<ul>
<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/try.sh">view example try.sh</a></li>
<li><a href="next/try.sh">download example try.sh</a></li>
<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/try.alt.sh">view example try.alt.sh</a></li>
<li><a href="next/try.alt.sh">download example try.alt.sh</a></li>
</ul>
<p>The template <code>try.sh</code> script can be used as a starting point, or you can look at
some of the others in the website, to get some ideas.</p>
<p>It is not detrimental to your chances of winning if you do not include one as
not all submissions can make use of them. Nevertheless, it is helpful to include
ways to use your program, and if you have creative ways this can be a bonus. It
@@ -1086,10 +1091,11 @@ discussion</a>.</p>
<p>There are unfortunately some warnings that cannot be disabled; they are always
enabled whatever warning options you have enabled. Also, there is a warning that
is enabled whenever you act on <code>char *</code>s, saying it is unsafe buffer usage, even
when it’s not (this might be enabled by <code>-Weverything</code> but it might not be; for
more details on why we use <code>-Weverything</code> in Clang see the FAQ on
“<a href="#weverything"><code>-Weverything</code></a>”), and it is not detrimental to your submission
if you disable this. This warning happens to be <code>-Wno-unsafe-buffer-usage</code>.</p>
when it’s not. This might be enabled by <code>-Weverything</code> but it might not be; for
more details on why we use <code>-Weverything</code> in Clang see the
FAQ on “<a href="#weverything">-Weverything</a>”.</p>
<p>It is not detrimental to your submission if you disable this, which you can do
by specifying <code>-Wno-unsafe-buffer-usage</code>.</p>
<p>So in short, no you should not worry about these as they are sometimes
inevitable in obfuscated code and even non-obfuscated code.</p>
<p>If you <em>can</em> work past this it might be good but this is not something that
@@ -3066,7 +3072,7 @@ extension <code>.md</code>.</p></li>
<code>"winner.alt.c"</code> or <code>"prog.alt.c"</code>; this is also what the <code>file_path</code> will be.
The <code>entry_text</code> will typically (not always but almost always) be <code>"alternate source code"</code>.</p>
<p>Many entries have a script (or scripts) for the <code>Try</code> section in their index.html file.
Usually this is called <code>try.sh</code> for the entry and <code>try.alt.sh</code> for the alternate
Usually this is called <code>try.sh</code> for the winning entry and <code>try.alt.sh</code> for the alternate
source code (if there is an alternate version). Some, however, have another file
name. The <code>entry_text</code> for the <code>try</code> scripts will be <code>script to try entry</code> or
something along those lines.</p>
@@ -3086,7 +3092,7 @@ repo</a>
contains information about how to find and compile the mkiocccentry
toolkit, which includes the IOCCC version of the <code>jparse(1)</code> tool, located
under the <code>mkiocccentry</code> directory as <code>jparse/jparse</code>.</p>
<p>Additionally you may install the <code>jparse(1)</code> tool from the <a href="https://github.com/xexyl/jparse">jparse
<p>Additionally you may install the <code>jparse(1)</code> tool from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry
repo</a>:</p>
<pre class="&lt;!--sh--&gt;"><code> git clone https://github.com/ioccc-src/mkiocccentry.git
cd mkiocccentry &amp;&amp; make clobber all&quot; 1&gt;&amp;2
@@ -3102,7 +3108,9 @@ verbosity with the <code>-v</code> option. For instance:</p>
the tool.</p>
<p><strong>NOTE</strong>: the <code>jparse</code> subdirectory is a clone of the official <a href="https://github.com/xexyl/jparse/issues">jparse
repo</a> but we recommend you compile and
install via the <code>mkiocccentry</code> repo because it has the dependencies built in.</p>
install via the <code>mkiocccentry</code> repo because it has the dependencies built in,
and because the <code>mkiocccentry</code> copy is that which is used by the current IOCCC,
as the two can be different at times.</p>
<p>Jump to: <a href="#">top</a></p>
<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">
faq.md
+21 -12
View File
@@ -578,11 +578,16 @@ Jump to: [top](#)
If your submission has more than one use, or if you have interesting ways to
invoke your program, perhaps using other commonly installed tools (or tools
included in your submission), it can be helpful to include a `try.sh` script.
included in your submission), it can be helpful to include a `try.sh` script:
A [template try.sh](next/try.sh) can be used as a
starting point, or you can look at some of the others in the website, to get
some ideas.
- [view example try.sh](%%REPO_URL%%/next/try.sh)
- [download example try.sh](next/try.sh)
- [view example try.alt.sh](%%REPO_URL%%/next/try.alt.sh)
- [download example try.alt.sh](next/try.alt.sh)
The template `try.sh` script can be used as a starting point, or you can look at
some of the others in the website, to get some ideas.
It is not detrimental to your chances of winning if you do not include one as
not all submissions can make use of them. Nevertheless, it is helpful to include
@@ -844,10 +849,12 @@ Jump to: [top](#)
There are unfortunately some warnings that cannot be disabled; they are always
enabled whatever warning options you have enabled. Also, there is a warning that
is enabled whenever you act on `char *`s, saying it is unsafe buffer usage, even
when it's not (this might be enabled by `-Weverything` but it might not be; for
more details on why we use `-Weverything` in Clang see the FAQ on
"[`-Weverything`](#weverything)"), and it is not detrimental to your submission
if you disable this. This warning happens to be `-Wno-unsafe-buffer-usage`.
when it's not. This might be enabled by `-Weverything` but it might not be; for
more details on why we use `-Weverything` in Clang see the
FAQ on "[-Weverything](#weverything)".
It is not detrimental to your submission if you disable this, which you can do
by specifying `-Wno-unsafe-buffer-usage`.
So in short, no you should not worry about these as they are sometimes
inevitable in obfuscated code and even non-obfuscated code.
@@ -3280,7 +3287,7 @@ The `entry_text` will typically (not always but almost always) be `"alternate
source code"`.
Many entries have a script (or scripts) for the `Try` section in their index.html file.
Usually this is called `try.sh` for the entry and `try.alt.sh` for the alternate
Usually this is called `try.sh` for the winning entry and `try.alt.sh` for the alternate
source code (if there is an alternate version). Some, however, have another file
name. The `entry_text` for the `try` scripts will be `script to try entry` or
something along those lines.
@@ -3306,8 +3313,8 @@ contains information about how to find and compile the mkiocccentry
toolkit, which includes the IOCCC version of the `jparse(1)` tool, located
under the `mkiocccentry` directory as `jparse/jparse`.
Additionally you may install the `jparse(1)` tool from the [jparse
repo](https://github.com/xexyl/jparse):
Additionally you may install the `jparse(1)` tool from the [mkiocccentry
repo](https://github.com/ioccc-src/mkiocccentry):
``` <!--sh-->
git clone https://github.com/ioccc-src/mkiocccentry.git
@@ -3337,7 +3344,9 @@ the tool.
**NOTE**: the `jparse` subdirectory is a clone of the official [jparse
repo](https://github.com/xexyl/jparse/issues) but we recommend you compile and
install via the `mkiocccentry` repo because it has the dependencies built in.
install via the `mkiocccentry` repo because it has the dependencies built in,
and because the `mkiocccentry` copy is that which is used by the current IOCCC,
as the two can be different at times.
Jump to: [top](#)
next/guidelines.html
+143 -55
View File
@@ -465,7 +465,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
</div>
</div>
<p class="leftbar">
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.25 2024-12-04</strong>.
These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.25 2024-12-05</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>
@@ -535,8 +535,10 @@ The <a href="rules.html#rule2b">Rule 2b</a> size has <strong>increased from 2053
bytes.
</p>
<p class="leftbar">
The new default way to compile submissions: <code>-std=gnu17 -O3 -g3 -Wall -Wextra -pedantic</code>. See below for more details about the example Makefile
for more help.
The new default way to compile submissions: <code>-std=gnu17 -O3 -g3 -Wall -Wextra -pedantic</code>.
You <strong>are encouraged</strong> to use the example Makefile here, rather than the
<code>mkiocccentry</code> repo. For details and help, see below in the <a href="#makefile">Makefile
section</a>.
</p>
<p class="leftbar">
Submissions are in the form of a single xz compressed tarball.
@@ -551,11 +553,6 @@ repo</a>.
to account for the new <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a> tools.
</p>
<p class="leftbar">
You <strong>are encouraged</strong> to use <a href="Makefile.example">this
Makefile.example</a>,
rather than the one at the <code>mkiocccentry</code> repo.
</p>
<p class="leftbar">
The IOCCC submission URL, <a href="../status.html#open">when the IOCCC is open</a>, is
<a href="https://submit.ioccc.org/">submit.ioccc.org</a>.
</p>
@@ -787,27 +784,40 @@ jparse</a>, for more
details.
</p>
<p class="leftbar">
The original <code>jparse</code> code, co-developed by Landon and Cody Boone Ferguson in
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">
<p>You do <strong>NOT</strong> need to install <code>jparse</code>! The <code>mkiocccentry</code> tools link in the
static library from the <code>mkiocccentry</code> clone! This also goes for the
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. In other words,
<code>mkiocccentry</code> contains <strong>everything</strong> you need.</p>
<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 this we will not include it here again.
As we already discussed how to invoke <code>mkiocccentry</code>, we will not include it
here again.
</p>
<p class="leftbar">
This tool was originally part of a winning entry by Anthony C Howe, but with
some modifications over time, as things have changed.
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>
@@ -824,12 +834,18 @@ See the
FAQ on “<a href="../faq.html#mkiocccentry_bugs">reporting mkiocccentry bugs</a>”.
</p>
<p class="leftbar">
Assuming that <code>chkentry(1)</code> 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
executed. In this case, there should be no problems as <code>mkiocccentry(1)</code> should
executed. In this case, there should be no problems, as <code>mkiocccentry(1)</code> should
<strong>NOT</strong> form a tarball if there are any issues.
</p>
<p class="leftbar">
If <code>mkiocccentry(1)</code> is used and <code>chkentry(1)</code> fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
<code>mkiocccentry(1)</code>, <code>chkentry(1)</code> or possibly <code>jparse</code>, though these are quite
unlikely.
</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
@@ -918,7 +934,7 @@ FAQ on “<a href="../faq.html#mkiocccentry_bugs">report mkiocccentry bugs</a>
As you can see, the use of <code>mkiocccentry(1)</code> is <strong>HIGHLY RECOMMENDED</strong>.
</p>
<div id="bugs">
<h1 id="problemsbugs-in-tools">Problems/bugs in tools</h1>
<h1 id="problems-andor-bugs-in-tools">Problems and/or bugs in tools</h1>
</div>
<p class="leftbar">
Although the tools have been tested quite a bit, and although it is quite
@@ -936,42 +952,88 @@ bug; it is a judgement call; if it’s a bug it’ll be addressed and if it’s
that’s OK too!
</p>
<div id="make">
<div id="makefile">
<h1 id="makefiles">Makefiles</h1>
</div>
</div>
<p class="leftbar">
<p>We <strong>recommend</strong> that you use the <a href="Makefile.example">example
Makefile</a>,
renamed as <code>Makefile</code> of course, as the starting point for your submission’s
required <code>Makefile</code>. Feel free to modify the <code>Makefile</code> to suit your obfuscated
needs.</p>
We <strong>recommend</strong> AND <strong>encourage</strong> you to use the example Makefile <strong>here</strong>,
rather than the <code>mkiocccentry</code> repo’s <code>Makefile.example</code>, renamed as <code>Makefile</code>
of course, as the starting point for your submission’s required <code>Makefile</code>:
</p>
<ul>
<li><p class="leftbar">
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/Makefile.example">view example
Makefile</a>
</p></li>
<li><p class="leftbar">
<a href="Makefile.example"
download="Makefile">download example Makefile</a>
</p></li>
</ul>
<p class="leftbar">
The rest of this section will assume that you are using some variant of the
<a href="Makefile.example">example Makefile</a>,
renamed as <code>Makefile</code> of course.
Feel free to modify the <code>Makefile</code> to suit your obfuscated
needs.
</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>
<p class="leftbar">
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="flags">
<h2 id="default-compiler-flags">Default compiler flags</h2>
</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>.
submission’s <code>Makefile</code>, we <strong>will</strong> compile using <code>-std=gnu17 -O3 -g3</code>!
</p>
<p class="leftbar">
It is <strong>OK</strong> to require your submission to not be 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 and adjust your <code>Makefile</code> accordingly.
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>.
</p>
<div id="compilers">
<h2 id="default-compiler">Default compiler</h2>
</div>
<p class="leftbar">
<strong>IMPORTANT NOTE</strong>: The use of <code>-std=gnu17</code> does <strong>NOT</strong> imply the use of the <code>gcc</code>
compiler! We often start by compiling using the <strong>clang</strong> C compiler instead.
</p>
<p class="leftbar">
<strong>PLEASE NOTE</strong>: in macOS, the compiler <code>gcc</code> found at <code>/usr/bin/gcc</code> is
in truth the <code>clang</code> compiler, as <code>/usr/bin/gcc --version</code> will show!
</p>
<div id="cstd">
<div id="standard">
<h2 id="c-standard">C standard</h2>
</div>
</div>
<p class="leftbar">
You may change the standard under which your submission is compiled
by modifying the <code>CSTD</code> Makefile variable. For example, to use <code>c17</code> instead:
</p>
<pre><code> CSTD= -std=c17</code></pre>
<div id="opt">
<h2 id="default-optimisation-level">Default optimisation level</h2>
</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:
</p>
<pre><code> OPT= -O0 -g3</code></pre>
<div id="warnings">
<h2 id="compiler-warnings">Compiler warnings</h2>
</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
@@ -982,11 +1044,11 @@ cited there. This goes even if your version does not trigger a warning as some
other version might!
</p>
<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 debug symbols:
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.
</p>
<pre><code> OPT= -O0 -g3</code></pre>
<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
@@ -999,7 +1061,7 @@ more strict <code>-Wall -Wextra -pedantic</code> mode:
</p>
<pre><code> CWARN= -Wall -Wextra -pedantic</code></pre>
<p class="leftbar">
The two previous guidelines may be thought by some as being somewhat
The two previous guidelines might be thought by some as being somewhat
contradictory. Isn’t life, and isn’t trying to satisfy “contradictory customer
requirements” all too often like that? :-) Try to minimize warnings if you
can.
@@ -1019,13 +1081,18 @@ 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).
</p>
<p class="leftbar">
Additionally: some compilers like to warn about certain use of <code>char *</code>s which
is not only dubious itself, but it obviously can’t (always) be avoided, so you
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>-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>”
and the
FAQ on “<a href="../faq.html#weverything"><code>-Weverything</code></a>”.
FAQ on “<a href="../faq.html#weverything">-Weverything</a>”.
</p>
<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. :-)
And even without <code>-Weverything</code> there can be warnings, as noted above.
</p>
<p class="leftbar">
If your submission issues lots of warnings but is otherwise
@@ -1036,10 +1103,6 @@ produce a compiler <strong>error</strong> and refuse to compile your code: unles
reason that is what you intend to happen in which case document that too in your
<code>remarks.md</code> file. :-)
</p>
<p class="leftbar">
<strong>PLEASE NOTE</strong>: in macOS, the compiler <code>gcc</code> found at <code>/usr/bin/gcc</code> is
in truth the <code>clang</code> compiler, as <code>/usr/bin/gcc --version</code> will show!
</p>
<p>All other things being equal, a program that must turn off fewer
warnings will be considered better, for certain values of better.</p>
<p class="leftbar">
@@ -1059,16 +1122,25 @@ 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.
</p>
<div id="macros">
<h2 id="defining-macros-in-the-makefile">Defining macros in the Makefile</h2>
</div>
<p class="leftbar">
If you need to define something on the compile line, use
the <code>CDEFINE</code> Makefile variable. For example:
</p>
<pre><code> CDEFINE= -Dfoo -Dbar=baz</code></pre>
<div id="include">
<h2 id="include-files-in-the-makefile">Include files in the Makefile</h2>
</div>
<p class="leftbar">
If you need to include a file on the command line, use
the <code>CINCLUDE</code> Makefile variable. For example:
If you need to include a file (as in <code>#include</code>) on the command line, use the
<code>CINCLUDE</code> Makefile variable. For example:
</p>
<pre><code> CINCLUDE= -include stdio.h</code></pre>
<div id="magic">
<h2 id="magic-in-the-makefile">Magic in the Makefile</h2>
</div>
<p class="leftbar">
If you need to add other “<strong>magic</strong>” flags to your compile line,
use the <code>COTHER</code> Makefile variable. For example:
@@ -1089,16 +1161,32 @@ Again, please note that in macOS, <code>/usr/bin/gcc</code> is actually <code>cl
</div>
<p class="leftbar">
We <strong>LIKE</strong> submissions that use an edited variant of the
<a href="Makefile.example">example Makefile</a>,
example Makefile, as described in the <a href="#makefile">Makefile section</a>,
renamed as <code>Makefile</code> of course. This makes it easier for the <a href="../judges.html">IOCCC Judges</a>
to test your submission. And if your submissions wins, it makes it easier to integrate it into
the <a href="https://www.ioccc.org/index.html">Official IOCCC winner website</a>.
</p>
<p class="leftbar">
We <strong>LIKE</strong> submissions that use an edited version of the
<a href="try.sh">try.sh</a> example script (and if you have alternate code,
the same applies with the <a href="try.alt.sh">try.alt.sh</a>
example script). Of course, it is quite possible that only one invocation is
<code>try.sh</code> example script (and if you have alternate code,
the same applies with the <code>try.alt.sh</code> script):
</p>
<ul>
<li><p class="leftbar">
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/try.sh">view example try.sh</a>
</p></li>
<li><p class="leftbar">
<a href="try.sh">download example try.sh</a>
</p></li>
<li><p class="leftbar">
<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/next/try.alt.sh">view example try.alt.sh</a>
</p></li>
<li><p class="leftbar">
<a href="try.alt.sh">download example try.alt.sh</a>
</p></li>
</ul>
<p class="leftbar">
Of course, it is quite possible that only one invocation is
possible, so it is not necessarily detrimental to your submission if you do not
include one, though we do like interesting and creative uses of submissions. See
also the
@@ -1341,9 +1429,9 @@ they do not work as documented.</p>
is NOT the smallest C source file that when compiled and run, dumps core:</p>
<pre><code> main;</code></pre>
<p class="leftbar">
Unless you specify <code>-fwritable-strings</code> (see <code>COTHER</code> in the <a href="Makefile.example">example
Makefile</a>)
do not assume this sort of code will work:
Unless you specify <code>-fwritable-strings</code> (see <code>COTHER</code> in the example
Makefile, described in the <a href="#makefile">Makefile section</a>), do not assume this
sort of code will work:
</p>
<pre><code> char *T = &quot;So many primes, so little time!&quot;;
...
@@ -1564,9 +1652,9 @@ CPU, we might just try your submission on that emulator as well :-)
<p class="leftbar">
If your submission <strong>MUST</strong> run only on a 64-bit or 32-bit architecture,
then you <strong>MUST</strong> specify the <code>-arch</code> on your command line
(see <code>ARCH</code> in the <a href="Makefile.example">example
Makefile</a>). Do not assume a processor word size without
specifying <code>-arch</code>. For example:
(see <code>ARCH</code> in the example
Makefile, described in <a href="#makefile">Makefile section</a>). Do not assume a
processor word size without specifying <code>-arch</code>. For example:
</p>
<pre><code> ARCH= -m64</code></pre>
<p class="leftbar">
next/guidelines.md
+153 -59
View File
@@ -52,7 +52,7 @@ Jump to: [top](#)
</div>
<p class="leftbar">
These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-04**.
These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-05**.
</p>
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -140,8 +140,10 @@ bytes.
</p>
<p class="leftbar">The new default way to compile submissions: `-std=gnu17 -O3 -g3
-Wall -Wextra -pedantic`. See below for more details about the example Makefile
for more help.
-Wall -Wextra -pedantic`.
You **are encouraged** to use the example Makefile here, rather than the
`mkiocccentry` repo. For details and help, see below in the [Makefile
section](#makefile).
</p>
<p class="leftbar">
@@ -159,12 +161,6 @@ repo](https://github.com/ioccc-src/mkiocccentry).
to account for the new [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) tools.
</p>
<p class="leftbar">
You **are encouraged** to use [this
Makefile.example](Makefile.example),
rather than the one at the `mkiocccentry` repo.
</p>
<p class="leftbar">
The IOCCC submission URL, [when the IOCCC is open](../status.html#open), is
[submit.ioccc.org](https://submit.ioccc.org/).
@@ -450,18 +446,27 @@ details.
</p>
<p class="leftbar">
The original `jparse` code, co-developed by Landon and Cody Boone Ferguson in
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`! The `mkiocccentry` tools link in the
static library from the `mkiocccentry` clone! This also goes for the
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. In other words,
`mkiocccentry` contains **everything** you need.
[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](#)
@@ -472,12 +477,18 @@ Jump to: [top](#)
<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 this we will not include it here again.
As we already discussed how to invoke `mkiocccentry`, we will not include it
here again.
</p>
<p class="leftbar">
This tool was originally part of a winning entry by Anthony C Howe, but with
some modifications over time, as things have changed.
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](#)
@@ -500,12 +511,19 @@ FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
</p>
<p class="leftbar">
Assuming that `chkentry(1)` 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
executed. In this case, there should be no problems as `mkiocccentry(1)` should
executed. In this case, there should be no problems, as `mkiocccentry(1)` should
**NOT** form a tarball if there are any issues.
</p>
<p class="leftbar">
If `mkiocccentry(1)` is used and `chkentry(1)` fails to validate either of the
files, then unless it is a system specific problem, it is likely a bug in
`mkiocccentry(1)`, `chkentry(1)` or possibly `jparse`, though these are quite
unlikely.
</p>
<p class="leftbar">
Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
@@ -620,7 +638,7 @@ As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
<div id="bugs">
# Problems/bugs in tools
# Problems and/or bugs in tools
</div>
<p class="leftbar">
@@ -642,20 +660,30 @@ that's OK too!
<div id="make">
<div id="makefile">
# Makefiles
</div>
</div>
<p class="leftbar">
We **recommend** that you use the [example
Makefile](Makefile.example),
renamed as `Makefile` of course, as the starting point for your submission's
required `Makefile`. Feel free to modify the `Makefile` to suit your obfuscated
needs.
We **recommend** AND **encourage** you to use the example Makefile **here**,
rather than the `mkiocccentry` repo's `Makefile.example`, renamed as `Makefile`
of course, as the starting point for your submission's required `Makefile`:
</p>
- <p class="leftbar">[view example
Makefile](%%REPO_URL%%/next/Makefile.example)</p>
- <p class="leftbar"><a href="Makefile.example"
download="Makefile">download example Makefile</a></p>
<p class="leftbar">
The rest of this section will assume that you are using some variant of the
[example Makefile](Makefile.example),
renamed as `Makefile` of course.
Feel free to modify the `Makefile` to suit your obfuscated
needs.
</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`.
</p>
<p class="leftbar">
@@ -663,23 +691,49 @@ We suggest that you compile your submission with a commonly available
`-std=gnu17` (ISO C 2017 with GNU extensions) C compiler.
</p>
<div id="flags">
## Default compiler flags
</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`.
submission's `Makefile`, we **will** compile using `-std=gnu17 -O3 -g3`!
</p>
<p class="leftbar">
It is **OK** 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 `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`.
</p>
<div id="compilers">
## Default compiler
</div>
<p class="leftbar">
**IMPORTANT NOTE**: The use of `-std=gnu17` does **NOT** imply the use of the `gcc`
compiler! We often start by compiling using the **clang** C compiler instead.
</p>
<p class="leftbar">
**PLEASE NOTE**: in macOS, the compiler `gcc` found at `/usr/bin/gcc` is
in truth the `clang` compiler, as `/usr/bin/gcc --version` will show!
</p>
<div id="cstd">
<div id="standard">
## C standard
</div>
</div>
<p class="leftbar">
You may change the standard under which your submission is compiled
by modifying the `CSTD` Makefile variable. For example, to use `c17` instead:
@@ -690,6 +744,24 @@ by modifying the `CSTD` Makefile variable. For example, to use `c17` instead:
CSTD= -std=c17
```
<div id="opt">
## Default optimisation level
</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:
</p>
``` <!---make-->
OPT= -O0 -g3
```
<div id="warnings">
## Compiler warnings
</div>
<p class="leftbar">
For compilers, such as `clang`, that have the `-Weverything` option,
while you may wish to try it, you should read our
@@ -701,14 +773,14 @@ other version might!
</p>
<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 debug symbols:
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.
</p>
``` <!---make-->
OPT= -O0 -g3
```
<div id="disabling-warnings">
## Disabling warnings
</div>
<p class="leftbar">
There is no real penalty for compiler warnings. Sometimes
@@ -727,7 +799,7 @@ more strict ` -Wall -Wextra -pedantic` mode:
```
<p class="leftbar">
The two previous guidelines may be thought by some as being somewhat
The two previous guidelines might be thought by some as being somewhat
contradictory. Isn't life, and isn't trying to satisfy "contradictory customer
requirements" all too often like that? :-) Try to minimize warnings if you
can.
@@ -750,13 +822,20 @@ about this, though it might be worth pointing out (see below for an example).
</p>
<p class="leftbar">
Additionally: some compilers like to warn about certain use of `char *`s which
is not only dubious itself, but it obviously can't (always) be avoided, so you
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
`-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)"
and the
FAQ on "[`-Weverything`](../faq.html#weverything)".
FAQ on "[-Weverything](../faq.html#weverything)".
</p>
<p class="leftbar">
If you do have to disable warnings due to `-Weverything` automatically being
included, you might wish to state this fact. :-)
And even without `-Weverything` there can be warnings, as noted above.
</p>
<p class="leftbar">
@@ -769,11 +848,6 @@ reason that is what you intend to happen in which case document that too in your
`remarks.md` file. :-)
</p>
<p class="leftbar">
**PLEASE NOTE**: in macOS, the compiler `gcc` found at `/usr/bin/gcc` is
in truth the `clang` compiler, as `/usr/bin/gcc --version` will show!
</p>
All other things being equal, a program that must turn off fewer
warnings will be considered better, for certain values of better.
@@ -813,6 +887,10 @@ 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.
</p>
<div id="macros">
## Defining macros in the Makefile
</div>
<p class="leftbar">
If you need to define something on the compile line, use
the `CDEFINE` Makefile variable. For example:
@@ -822,9 +900,13 @@ the `CDEFINE` Makefile variable. For example:
CDEFINE= -Dfoo -Dbar=baz
```
<div id="include">
## Include files in the Makefile
</div>
<p class="leftbar">
If you need to include a file on the command line, use
the `CINCLUDE` Makefile variable. For example:
If you need to include a file (as in `#include`) on the command line, use the
`CINCLUDE` Makefile variable. For example:
</p>
``` <!---make-->
@@ -832,6 +914,10 @@ the `CINCLUDE` Makefile variable. For example:
```
<div id="magic">
## Magic in the Makefile
</div>
<p class="leftbar">
If you need to add other "**magic**" flags to your compile line,
use the `COTHER` Makefile variable. For example:
@@ -860,7 +946,7 @@ Jump to: [top](#)
<p class="leftbar">
We **LIKE** submissions that use an edited variant of the
[example Makefile](Makefile.example),
example Makefile, as described in the [Makefile section](#makefile),
renamed as `Makefile` of course. This makes it easier for the [IOCCC Judges](../judges.html)
to test your submission. And if your submissions wins, it makes it easier to integrate it into
the [Official IOCCC winner website](https://www.ioccc.org/index.html).
@@ -868,9 +954,17 @@ the [Official IOCCC winner website](https://www.ioccc.org/index.html).
<p class="leftbar">
We **LIKE** submissions that use an edited version of the
[try.sh](try.sh) example script (and if you have alternate code,
the same applies with the [try.alt.sh](try.alt.sh)
example script). Of course, it is quite possible that only one invocation is
`try.sh` example script (and if you have alternate code,
the same applies with the `try.alt.sh` script):
</p>
- <p class="leftbar">[view example try.sh](%%REPO_URL%%/next/try.sh)</p>
- <p class="leftbar"><a href="try.sh">download example try.sh</a></p>
- <p class="leftbar">[view example try.alt.sh](%%REPO_URL%%/next/try.alt.sh)</p>
- <p class="leftbar"><a href="try.alt.sh">download example try.alt.sh</a></p>
<p class="leftbar">
Of course, it is quite possible that only one invocation is
possible, so it is not necessarily detrimental to your submission if you do not
include one, though we do like interesting and creative uses of submissions. See
also the
@@ -1161,9 +1255,9 @@ is NOT the smallest C source file that when compiled and run, dumps core:
```
<p class="leftbar">
Unless you specify `-fwritable-strings` (see `COTHER` in the [example
Makefile](Makefile.example))
do not assume this sort of code will work:
Unless you specify `-fwritable-strings` (see `COTHER` in the example
Makefile, described in the [Makefile section](#makefile)), do not assume this
sort of code will work:
</p>
``` <!---c-->
@@ -1426,9 +1520,9 @@ CPU, we might just try your submission on that emulator as well :-)
<p class="leftbar">
If your submission **MUST** run only on a 64-bit or 32-bit architecture,
then you **MUST** specify the `-arch` on your command line
(see `ARCH` in the [example
Makefile](Makefile.example)). Do not assume a processor word size without
specifying `-arch`. For example:
(see `ARCH` in the example
Makefile, described in [Makefile section](#makefile)). Do not assume a
processor word size without specifying `-arch`. For example:
</p>
``` <!---make-->
next/rules.html
+5 -4
View File
@@ -466,7 +466,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
</div>
<p>Jump to: <a href="#">top</a></p>
<p class="leftbar">
These <a href="rules.html">IOCCC rules</a> are version <strong>28.12 2024-12-04</strong>.
These <a href="rules.html">IOCCC rules</a> are version <strong>28.12 2024-12-05</strong>.
</p>
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="guidelines.html">IOCCC guidelines</a>.</p>
<p>Jump to: <a href="#">top</a></p>
@@ -905,7 +905,7 @@ those requirements.
<p class="leftbar">
The <code>Makefile</code> <strong>MUST</strong> be a <strong>non</strong>-empty file in <strong><a href="https://www.gnu.org/software/make/manual/make.html">GNU
Makefile</a></strong> form. See the
<a href="Makefile.example">Makefile.example</a>,
<a href="guidelines.html#makefile">Makefile section in the guidelines</a>,
the
FAQ on “<a href="../faq.html#submission_makefiles">submission Makefile</a>”
and the
@@ -1092,8 +1092,9 @@ make(1) compatibility the IOCCC
supports</a> for more details.</p>
<p class="leftbar">
You are <strong>ENCOURAGED</strong> to use
<a href="Makefile.example">Makefile.example</a>,
renamed as <code>Makefile</code> of course, for help in constructing your <code>Makefile</code>.
Makefile example, renamed as <code>Makefile</code> of course, for help in constructing your
<code>Makefile</code>. See the <a href="guidelines.html#makefile">Makefile section</a> in the
guidelines for more details.
</p>
<p>The target of the Makefile must be called <code>prog</code>. The original
C source file must be called <code>prog.c</code>.</p>
next/rules.md
+5 -4
View File
@@ -57,7 +57,7 @@ Jump to: [top](#)
Jump to: [top](#)
<p class="leftbar">
These [IOCCC rules](rules.html) are version **28.12 2024-12-04**.
These [IOCCC rules](rules.html) are version **28.12 2024-12-05**.
</p>
**IMPORTANT**: Be sure to read the [IOCCC guidelines](guidelines.html).
@@ -607,7 +607,7 @@ those requirements.
<p class="leftbar">
The `Makefile` **MUST** be a **non**-empty file in **[GNU
Makefile](https://www.gnu.org/software/make/manual/make.html)** form. See the
[Makefile.example](Makefile.example),
[Makefile section in the guidelines](guidelines.html#makefile),
the
FAQ on "[submission Makefile](../faq.html#submission_makefiles)"
and the
@@ -812,8 +812,9 @@ supports](../faq.html#make_compatibility) for more details.
<p class="leftbar">
You are **ENCOURAGED** to use
[Makefile.example](Makefile.example),
renamed as `Makefile` of course, for help in constructing your `Makefile`.
Makefile example, renamed as `Makefile` of course, for help in constructing your
`Makefile`. See the [Makefile section](guidelines.html#makefile) in the
guidelines for more details.
</p>
The target of the Makefile must be called `prog`. The original