From 4256b023270c2c8a5a11233017db22d6c64dea41 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Sat, 29 Nov 2025 17:35:58 -0800 Subject: [PATCH] checkpoint guideline fixes 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. --- next/guidelines.html | 273 +------------------------------- next/guidelines.md | 359 +------------------------------------------ sitemap.xml | 6 +- 3 files changed, 11 insertions(+), 627 deletions(-) diff --git a/next/guidelines.html b/next/guidelines.html index 6c0fb86b4..8f9bcc005 100644 --- a/next/guidelines.html +++ b/next/guidelines.html @@ -626,6 +626,8 @@ in the building and compiling of your submission.

Your Makefile MUST be compatible with GNU make and we suggest you use Makefile.example as a template, renamed as Makefile of course.

+

See the +FAQ on “What are the detailed recommendations for a submission Makefile?”.

Jump to: top

@@ -826,273 +828,8 @@ FAQ on “What is mkiocccentry in simpl

See FAQ on “What is the mkiocccentry tool, how do I obtain it and how do I use it”.

Jump to: top

-
-
-

Makefiles

-
-
-

-We recommend AND encourage you to use the example Makefile, -as the starting point for your submission’s required Makefile: -

- -

-Feel free to modify the Makefile to suit your obfuscation -needs. -

-

-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. -

-

-The rest of this section and its subsections will assume that you are using some -variant of the example Makefile, again renamed as Makefile. -

-

-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). -

-
-
-

Default compiler flags

-
-
-

-Unless you clearly state otherwise in your remarks.md file, AND put in -your submission’s Makefile, we will compile using -std=gnu17 -O3! -

-

-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. -

-

-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 for details for changing optimiser -flags. -

-

-For more fun when it comes to optimisers breaking code, see -1986/marshall/compilers.html. -

-
-

Default compiler

-
-

-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. -

-

-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! -

-
-
-

C standard

-
-
-

-You may change the standard under which your submission is compiled -by modifying the CSTD Makefile variable. For example, to use c99 instead: -

-
    CSTD= -std=c99
-
-
-
-
-
-

Default optimisation level

-
-
-
-
-
-

-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: -

-
    OPT= -O0 -g3
-
-
-

Compiler warnings

-
-
-

-The default warning flags are set via the CWARN variable, as shown in the -example Makefile: -

-
    # Common C compiler warning flags
-    #
-    CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN}
-

-For details on CSILENCE and CUNKNOWN, see the section on disabling -warnings. -

-
-

The -Weverything option

-
-

-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”. -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! -

-

-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” -for more details. -

-

-If “clang” is NOT in ${CC}, the CWARN variable will not be further -modified. -

-

-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. -

-

-We LIKE code that has a minimum of warnings, especially under the -more strict -Wall -Wextra -pedantic mode: -

-
    CWARN= -Wall -Wextra -pedantic
-

-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. -

-

-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). -

-

-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. -

-

-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” -and the -FAQ on “-Weverything”. -

-

Disabling warnings

-

-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. -

-

-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. :-) -

-

All other things being equal, a program that must turn off fewer -warnings will be considered better, for certain values of better.

-

-To turn off a compiler warning, in your submission’s Makefile, -try something such as: -

-
    CSILENCE= -Wno-some-thing -Wno-another-thing
-

-For instance: -

-
    CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation
-

-If you do add “-Wno-foo” to your Makefile, consider changing: -

-
    CUNKNOWN=
-

-to: -

-
    CUNKNOWN= -Wno-unknown-warning-option
-

-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. -

-
-

Defining macros in the Makefile

-
-

-If you need to define something on the compile line, use -the CDEFINE Makefile variable. For example: -

-
    CDEFINE= -Dfoo -Dbar=baz
-

-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. -

-
-

Include files in the Makefile

-
-

-If you need to include a file (as in #include) on the command line, use the -CINCLUDE Makefile variable. For example: -

-
    CINCLUDE= -include stdio.h
-
-

Magic in the Makefile

-
-

-If you need to add other “magic” flags to your compile line, -use the COTHER Makefile variable. For example: -

-
    COTHER= -fno-math-errno
-

-NOTE: We only recommend using “magic” flags if BOTH gcc -and clang support it. -

-

-Again, please note that in macOS, /usr/bin/gcc is actually clang! -

-
-

The clobber rule

-
-

-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. -

General Guidelines

-
-
-

General Overall Guidelines

These guideline are hints and suggestions, NOT IOCCC rules.

@@ -1616,14 +1353,12 @@ You do?!? (Except on Tuesday?)

unless you count this one, in which case there are 3. :-)

NOTE: The previous guideline in this spot has been replaced by this guideline:

-

-

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 perhaps misleading. Therefore, it might be wise for you to not fail to consider -to not do so, accordingly. Thank you very much (allegedly).

-
+to not do so, accordingly. Thank you very much (allegedly).

Any complaints about the above guideline could be addressed to the Speaker of the House of Commons, or to the speaker of your national diff --git a/next/guidelines.md b/next/guidelines.md index 880c7f5ca..d52c7c9ed 100644 --- a/next/guidelines.md +++ b/next/guidelines.md @@ -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](#) -

-
-# Makefiles -
-
- -

-We **recommend** AND **encourage** you to use the example Makefile, -as the starting point for your submission's required `Makefile`: -

- -- [view example Makefile](%%REPO_URL%%/next/Makefile.example) -- download example Makefile - -

-Feel free to modify the `Makefile` to suit your obfuscation -needs. -

- -

-**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. -

- -

-The rest of this section and its subsections will assume that you are using some -variant of the example `Makefile`, again renamed as `Makefile`. -

- -

-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)`. -

- -
-
-## Default compiler flags -
-
- -

-Unless you **clearly state** otherwise in your `remarks.md` file, **AND** put in -your submission's `Makefile`, we **will** compile using `-std=gnu17 -O3`! -

- -

-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. -

- -

-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. -

- -

-For more fun when it comes to optimisers breaking code, see -[1986/marshall/compilers.html](../1986/marshall/compilers.html). -

- - -
-## Default compiler -
- -

-**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. -

- -

-**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! -

- - -
-
-## C standard -
-
- -

-You may change the standard under which your submission is compiled -by modifying the `CSTD` Makefile variable. For example, to use `c99` instead: -

- - -``` - CSTD= -std=c99 -``` - -
-
-
-
-
-## Default optimisation level -
-
-
-
-
- -

-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: -

- -``` - OPT= -O0 -g3 -``` - -
-
-## Compiler warnings -
-
- -

-The default warning flags are set via the `CWARN` variable, as shown in the -example `Makefile`: -

- -``` - # Common C compiler warning flags - # - CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN} -``` - -

-For details on `CSILENCE` and `CUNKNOWN`, see the [section on disabling -warnings](#disabling-warnings). -

- -
-### The `-Weverything` option -
- -

-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! -

- -

-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. -

- -

-If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further -modified. -

- -

-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. -

- -

-We **LIKE** code that has a minimum of warnings, especially under the -more strict ` -Wall -Wextra -pedantic` mode: -

- -``` - CWARN= -Wall -Wextra -pedantic -``` - -

-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. -

- -

-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). -

- -

-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. -

- -

-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)". -

- -
-## Disabling warnings -
- -

-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. -

- -

-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. :-) -

- -All other things being equal, a program that must turn off fewer -warnings will be considered better, for certain values of better. - -

-To turn off a compiler warning, in your submission's `Makefile`, -try something such as: -

- -``` - CSILENCE= -Wno-some-thing -Wno-another-thing -``` - -

-For instance: -

- -``` - CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation -``` - -

-If you do add "`-Wno-foo`" to your Makefile, consider changing: -

- -``` - CUNKNOWN= -``` - -

-to: -

- -``` - CUNKNOWN= -Wno-unknown-warning-option -``` - -

-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. -

- -
-## Defining macros in the Makefile -
- -

-If you need to define something on the compile line, use -the `CDEFINE` Makefile variable. For example: -

- -``` - CDEFINE= -Dfoo -Dbar=baz -``` - -

-**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. -

- -
-## Include files in the Makefile -
- -

-If you need to include a file (as in `#include`) on the command line, use the -`CINCLUDE` Makefile variable. For example: -

- -``` - CINCLUDE= -include stdio.h -``` - - -
-## Magic in the Makefile -
- -

-If you need to add other "**magic**" flags to your compile line, -use the `COTHER` Makefile variable. For example: -

- -``` - COTHER= -fno-math-errno -``` - -

-**NOTE**: **We only recommend using "_magic_" flags if _BOTH_ `gcc` -_and_ `clang`** support it. -

- -

-Again, please note that in macOS, `/usr/bin/gcc` is actually `clang`! -

- - -
-## The clobber rule -
- -

-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. -

- -
# General Guidelines
-
# 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_:

-> 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 diff --git a/sitemap.xml b/sitemap.xml index a4d8d507e..c7a057904 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -16826,11 +16826,11 @@ https://www.ioccc.org/next/guidelines.html - 2025-11-29T23:08:54+00:00 + 2025-11-30T01:19:21+00:00 https://www.ioccc.org/next/guidelines.md - 2025-11-29T23:23:33+00:00 + 2025-11-30T01:18:54+00:00 https://www.ioccc.org/next/index.html @@ -16938,7 +16938,7 @@ https://www.ioccc.org/status.html - 2025-11-30T00:36:15+00:00 + 2025-11-30T01:25:49+00:00 https://www.ioccc.org/status.json