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

checkpoint guideline fixes

Browse Source 
Attempt to fix HTML5 errors.

Remove Makefile section from Guidelines as
this is in the FAQ.

Added links to Makefile FAQ in Guidelines.

Ran `make quick_www` to perform the above

TODO: Complete the correction for issue #244 ("Restore guidelines").

TODO: Continue to revise and improve the IOCCC guidelines as needed.

TODO: Fix typos/nits in the `next/guidelines.md` if needed.

TODO: Fix typos/nits in the `next/rules.md` if needed.
This commit is contained in:
Landon Curt Noll committed 2025-11-29 17:35:58 -08:00
1 parent c5bd5b33a4
commit 4256b02327
3 files changed
+11 -627
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

next/guidelines.md
+4 -355
View File
@@ -231,6 +231,9 @@ Your Makefile **MUST** be compatible with GNU `make` and we suggest you use
[Makefile.example](Makefile.example) as a template, renamed as Makefile of
course.
See the
FAQ on "[What are the detailed recommendations for a submission Makefile?](../faq.html#makefile_details)".
Jump to: [top](#)
@@ -506,364 +509,10 @@ FAQ on "[What is the mkiocccentry tool, how do I obtain it and how do I use it](
Jump to: [top](#)
<div id="make">
<div id="makefile">
# Makefiles
</div>
</div>
<p class="leftbar">
We **recommend** AND **encourage** you to use the example Makefile,
as the starting point for your submission's required `Makefile`:
</p>
- [view example Makefile](%%REPO_URL%%/next/Makefile.example)
- <a href="Makefile.example" download="Makefile">download example Makefile</a>
<p class="leftbar">
Feel free to modify the `Makefile` to suit your obfuscation
needs.
</p>
<p class="leftbar">
**Please** add a space between the `=` and the value of variables, in the
`Makefile`, making sure that the `=` comes immediately after the name. See the
example `Makefile` for examples.
</p>
<p class="leftbar">
The rest of this section and its subsections will assume that you are using some
variant of the example `Makefile`, again renamed as `Makefile`.
</p>
<p class="leftbar">
We suggest that you compile your submission with a commonly available
`-std=gnu17` (ISO C 2017 with GNU extensions) C compiler, via `clang(1)`
and/or `gcc(1)`.
</p>
<div id="cflags">
<div id="flags">
## Default compiler flags
</div>
</div>
<p class="leftbar">
Unless you **clearly state** otherwise in your `remarks.md` file, **AND** put in
your submission's `Makefile`, we **will** compile using `-std=gnu17 -O3`!
</p>
<p class="leftbar">
It **is OK** if you need to require your submission to **NOT be** compiled
using the default `-std=gnu17 -O3` settings. Simply **explain why**
your submission should NOT be compiled using `-std=gnu17 -O3` in
your `remarks.md` file, **AND** adjust your `Makefile` accordingly.
</p>
<p class="leftbar">
One reason that you might have to change the flags, is that the optimiser is
known to break some programs, but there are certainly other possible valid
reasons. Again, just update the `Makefile` and explain it in your `remarks.md`.
See the [optimiser section](#optimiser) for details for changing optimiser
flags.
</p>
<p class="leftbar">
For more fun when it comes to optimisers breaking code, see
[1986/marshall/compilers.html](../1986/marshall/compilers.html).
</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 `c99` instead:
</p>
``` <!---make-->
CSTD= -std=c99
```
<div id="opt">
<div id="optimization">
<div id="optimisation">
<div id="optimizer">
<div id="optimiser">
## Default optimisation level
</div>
</div>
</div>
</div>
</div>
<p class="leftbar">
You may change the level of optimization and compiler debug level
that your submission is compiled with, by modifying the `OPT` Makefile variable.
For example, to compile without optimization, and to include debug symbols:
</p>
``` <!---make-->
OPT= -O0 -g3
```
<div id="warnings">
<div id="cwarn">
## Compiler warnings
</div>
</div>
<p class="leftbar">
The default warning flags are set via the `CWARN` variable, as shown in the
example `Makefile`:
</p>
``` <!---sh-->
# Common C compiler warning flags
#
CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN}
```
<p class="leftbar">
For details on `CSILENCE` and `CUNKNOWN`, see the [section on disabling
warnings](#disabling-warnings).
</p>
<div id="weverything">
### The `-Weverything` option
</div>
<p class="leftbar">
For compilers, such as `clang`, that have the `-Weverything` option,
while you may wish to try it, you should read our
FAQ on "[clang -Weverything](../faq.html#weverything)".
We do **NOT** recommend that you put
the use of `-Weverything` into your submission's `Makefile` for the reasons
cited there. This goes even if your version does not trigger a warning as some
other version might!
</p>
<p class="leftbar">
On the other hand, if `${CC}` has "`clang`" in the name, the example `Makefile` will
automatically enable `-Weverything`, so you might have to use `-Wno-foo`
options anyway, as detailed below. See the
FAQ on "[-Weverything](../faq.html#weverything)"
for more details.
</p>
<p class="leftbar">
If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further
modified.
</p>
<p class="leftbar">
There is no real penalty for compiler warnings. Sometimes
compiler warnings cannot be helped: especially in the case of
obfuscated C. :-) So if you cannot easily get rid of a compiler
warning, try not to fret too much.
</p>
<p class="leftbar">
We **LIKE** code that has a minimum of warnings, especially under the
more strict ` -Wall -Wextra -pedantic` mode:
</p>
``` <!---make-->
CWARN= -Wall -Wextra -pedantic
```
<p class="leftbar">
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.
</p>
<p class="leftbar">
If you manage to produce very few warnings, or perhaps no warnings at
all under the `-Wall -Wextra -pedantic` mode, then by all means brag about it in
your `remarks.md` file **AND BE SURE TO TELL US** the OS, OS version, compiler
and compiler version in which you observed this occurring (in case our OS and
compiler produces a different result: so your submission won't be penalized for
not meeting your claims).
</p>
<p class="leftbar">
On the other hand, some warnings cannot be disabled and are enabled by compilers
without any warning option specified. These are sometimes inevitable in
obfuscated code and even in some non-obfuscated code, and you should not worry
about this, though it might be worth pointing out.
</p>
<p class="leftbar">
For instance, some compilers like to warn about use of pointers as arrays, which seems to
be dubious, as it obviously can't (always) be avoided, being a big part of C, so
you should not worry about this either; this is the warning
`-Wunsafe-buffer-usage` and the way to disable it is `-Wno-unsafe-buffer-usage`.
See also the
FAQ on "[forced warnings](../faq.html#forced_warnings)"
and the
FAQ on "[-Weverything](../faq.html#weverything)".
</p>
<div id="disabling-warnings">
## Disabling warnings
</div>
<p class="leftbar">
If you do have to disable warnings due to `-Weverything` automatically being
included, you might wish to state this fact in your `remarks.md` file.
And even without `-Weverything` there can be warnings, as noted above.
</p>
<p class="leftbar">
If your submission issues lots of warnings but is otherwise
marvelously obfuscated in multiple levels, don't worry about it. Nevertheless,
be sure that the warnings do not constitute a potential "**show stopper**"
compiler problem. Be sure that compilers such as both `gcc` and `clang` won't
produce a compiler **error** and refuse to compile your code: unless for some
reason that is what you intend to happen in which case document that too in your
`remarks.md` file. :-)
</p>
All other things being equal, a program that must turn off fewer
warnings will be considered better, for certain values of better.
<p class="leftbar">
To turn off a compiler warning, in your submission's `Makefile`,
try something such as:
</p>
``` <!---make-->
CSILENCE= -Wno-some-thing -Wno-another-thing
```
<p class="leftbar">
For instance:
</p>
``` <!---make-->
CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation
```
<p class="leftbar">
If you do add "`-Wno-foo`" to your Makefile, consider changing:
</p>
``` <!---make-->
CUNKNOWN=
```
<p class="leftbar">
to:
</p>
``` <!---make-->
CUNKNOWN= -Wno-unknown-warning-option
```
<p class="leftbar">
Some compilers have reported this as an error, however, and if you have
such a compiler you might want to not add it, or at least note in your
`remarks.md` file, which OS, OS version, compiler and compiler version
that has such a problem.
</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:
</p>
``` <!---make-->
CDEFINE= -Dfoo -Dbar=baz
```
<p class="leftbar">
**NOTE**: just because we offer a default way to use the `-D` option, we still
do not like excess use of `-D` to get past size limits, especially since you
could use `#define` in your code instead.
</p>
<div id="include">
## Include files in the Makefile
</div>
<p class="leftbar">
If you need to include a file (as in `#include`) on the command line, use the
`CINCLUDE` Makefile variable. For example:
</p>
``` <!---make-->
CINCLUDE= -include stdio.h
```
<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:
</p>
``` <!---make-->
COTHER= -fno-math-errno
```
<p class="leftbar">
**NOTE**: **We only recommend using "_magic_" flags if _BOTH_ `gcc`
_and_ `clang`** support it.
</p>
<p class="leftbar">
Again, please note that in macOS, `/usr/bin/gcc` is actually `clang`!
</p>
<div id="clobber">
## The clobber rule
</div>
<p class="leftbar">
When `make clobber` is invoked, we request that submissions be restored
to their original submission state. For example, any temporary files
(**including** the compiled program(s)) created during the build process, or
during execution should be removed by the `clobber` rule. In other words, the
only things that should be in the directory after running `make clobber` is what
is in your submission tarball itself.
</p>
<div id="general">
# General Guidelines
</div>
<div id="general"></div>
# General Overall Guidelines
@@ -1541,7 +1190,7 @@ unless you count this one, in which case there are 3. :-)
**NOTE**: The previous _guideline_ in this spot has been replaced by this _guideline_:
<p class="leftbar">
> You very well might not be completely prohibited from failing to not partly
You very well might not be completely prohibited from failing to not partly
misunderstand this particular _guideline_, but of course, we could not possibly
comment! :-) Nevertheless, you are neither prohibited, nor are you fully or partly
required to determine that this or the previous sentence is either false and/or