diff --git a/next/guidelines.html b/next/guidelines.html index 982edd9a8..82477ae56 100644 --- a/next/guidelines.html +++ b/next/guidelines.html @@ -460,15 +460,17 @@ and remains unaltered. All other uses must receive prior permission in writing by contacting the judges.

Jump to: top

-

IOCCC Guidelines version

+
+

IOCCC Guidelines version

+

-These IOCCC guidelines are version 28.19 2024-10-25. +These IOCCC guidelines are version 28.20 2024-11-26.

IMPORTANT: Be SURE to read the IOCCC rules.

Jump to: top

-

Change marks

+

Change marks

← Lines that start with this symbol indicate a change from the @@ -517,7 +519,7 @@ The submit URL should be active on or slightly before 2024-MMM-DD HH:MM: XXX - date/time is TBD - XXX

-The IOCCC rules, IOCCC +The IOCCC rules and these IOCCC guidelines will be available on the Official IOCCC website on or slightly before start of this IOCCC. Please check our FAQ on “how to submit” @@ -773,6 +775,31 @@ for how to use this tool in more detail.

Below are the tools that mkiocccentry(1) will run.

+

+The mkiocccentry(1) tool will execute a number of tools, some of which will +execute one or more additional tools; chkentry(1) will use the JSON parser +library jparse(3); see the jparse +README.md +in the mkiocccentry GitHub repo subdirectory +jparse as well as +the jparse library README.md +file +in the mkiocccentry GitHub repo subdirectory +jparse, for more +details. +

+

+The original jparse code, co-developed by Landon and Cody Boone Ferguson in +2022, comes from the jparse repo 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! +

+

+

You do NOT need to install jparse! The mkiocccentry tools link in the +static library from the mkiocccentry clone! This also goes for the +dbg and +dyn_array libraries. In other words, +mkiocccentry contains everything you need.

Jump to: top

iocccsize

@@ -780,18 +807,23 @@ Below are the tools that mkiocccentry(1) will run. 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.

+

+This tool was originally part of a winning entry by Anthony C Howe, but with +some modifications over time, as things have changed. +

Jump to: top

chkentry

mkiocccentry(1) will write two JSON files: .auth.json and .info.json. These files contain information about the author(s) and about the -submission. These files MUST pass the checks of chkentry(1). +submission. These files MUST pass the checks of chkentry(1)!

-If chkentry does not pass and you used mkiocccentry(1) it is possibly a +If chkentry does not pass and you used mkiocccentry(1) it is very likely a bug and you should report it as a bug at the mkiocccentry issues page. -See the FAQ on “report mkiocccentry bugs”. +See the +FAQ on “reporting mkiocccentry bugs”.

Assuming that chkentry(1) validates both .auth.json and @@ -803,7 +835,8 @@ executed. In this case, there should be no problems as mkiocccentry(1)validating .auth.json and/or .info.json files for more details on this tool and how you can use it to validate your -.auth.json and .info.json files. +.auth.json and .info.json files manually, without having to repackage your +submission.

You might also wish to see the @@ -824,14 +857,6 @@ page. PLEASE run the FAQ on “report mkiocccentry bugs”.

-Of course, it is also possible that mkiocccentry(1) or one or more of the -tools it calls (or another tool calls) to fail and it is NOT a bug. An -example problem is if there is not enough memory available or if some other -library or syscall fails. Nonetheless it might be worth reporting as a bug. It -is a judgement call; if it’s a bug it’ll be addressed and if it’s not that’s OK -too. -

-

As part of its sanity checks, txzchk(1) will run fnamchk(1) on the filename to verify that the name is valid. See the FAQ on “fnamchk” @@ -862,18 +887,23 @@ directory name of the tarball) then it is an error and you risk you wish to.

-To see more details on fnamchk and how to manually validate your submission +For more information on fnamchk and how to manually validate your submission tarball filename, see the FAQ on “fnamchk”.

+

+Note that the txzchk(1) tool uses fnamchk(1) tool as part of its algorithm. +Thus mkiocccentry(1) does not directly invoke fnamchk(1), although we will +in the judging process. +

-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 +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. But even if -everything checks out OK you should not expect that everything IS OK. +everything checks out OK you should NOT assume that everything IS OK.

It is extremely unlikely that fnamchk(1) reporting an invalid filename is a @@ -889,15 +919,36 @@ FAQ on “report mkiocccentry bugs

As you can see, the use of mkiocccentry(1) is HIGHLY RECOMMENDED.

+
+

Problems/bugs in tools

+

-

We recommend that you use the example +Although the tools have been tested quite a bit, and although it is quite +unlikely that there are bugs in it, it is nonetheless possible for bugs to +exist, as all programmers know. In this case, please ask for help or report what +you think is a bug as a bug, via the bug report issues page in the mkiocccentry +repo. +

+

+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 +bug. An example problem is if there is not enough memory available or if some +other library or syscall fails. Nonetheless it might be worth reporting as a +bug; it is a judgement call; if it’s a bug it’ll be addressed and if it’s not +that’s OK too! +

+
+

Makefiles

+
+

+

We recommend that you use the example Makefile from the IOCCC mkiocccentry repo, 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.

-The rest of these guidelines will assume that you are using some variant of the +The rest of this section will assume that you are using some variant of the example Makefile, renamed as Makefile of course.

@@ -906,12 +957,12 @@ We suggest that you compile your submission with a commonly available -std=gnu17 (ISO C 2017 with GNU extensions) C compiler.

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

It is OK 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 remarks.md file and adjust your Makefile accordingly.

@@ -967,13 +1018,14 @@ 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. +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).

-Additionally, some compilers like to warn about certain use of char *s which -is not only likely dubious itself 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 +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 +should not worry about this either; this is the warning +-Wno-unsafe-buffer-usage. See also the FAQ on “forced warnings” and the FAQ on “-Weverything”. @@ -987,21 +1039,28 @@ produce a compiler error and refuse to compile your code: unles reason that is what you intend to happen in which case document that too in your remarks.md file. :-)

+

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

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 -Wno-unknown-warning-option
+
    CSILENCE= -Wno-some-thing -Wno-another-thing
+

For instance:

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

-

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

+

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 and note it in your remarks.md. +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.

If you need to define something on the compile line, use @@ -1022,6 +1081,9 @@ use the COTHER Makefile variable. For example: 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! +

Jump to: top

diff --git a/next/guidelines.md b/next/guidelines.md index b88ac65d7..dc526176d 100644 --- a/next/guidelines.md +++ b/next/guidelines.md @@ -46,11 +46,13 @@ writing by [contacting the judges](../contact.html). Jump to: [top](#)
-## IOCCC Guidelines version +
+# IOCCC Guidelines version +

-These [IOCCC guidelines](guidelines.html) are version **28.19 2024-10-25**. +These [IOCCC guidelines](guidelines.html) are version **28.20 2024-11-26**.

**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html). @@ -58,7 +60,7 @@ These [IOCCC guidelines](guidelines.html) are version **28.19 2024-10-25**. Jump to: [top](#)
-### Change marks +## Change marks

**← Lines that start with this symbol indicate a change from the @@ -119,7 +121,7 @@ The submit URL should be active on or slightly before **2024-MMM-DD HH:MM:SS UTC

-The [IOCCC rules](rules.html), [IOCCC +The [IOCCC rules](rules.html) and these [IOCCC guidelines](guidelines.html) will be available on the [Official IOCCC website](https://www.ioccc.org) on or slightly before start of this IOCCC. Please check our FAQ on "[how to submit](../faq.html#submit)" @@ -435,6 +437,35 @@ for how to use this tool in more detail. Below are the tools that `mkiocccentry(1)` will run.

+

+The `mkiocccentry(1)` tool will execute a number of tools, some of which will +execute one or more additional tools; `chkentry(1)` will use the JSON parser +library `jparse(3)`; see the [jparse +README.md](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md) +in the [mkiocccentry GitHub repo subdirectory +jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse) as well as +the [jparse library README.md +file](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md) +in the [mkiocccentry GitHub repo subdirectory +jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse), for more +details. +

+ +

+The original `jparse` code, co-developed by Landon and 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! +

+ +

+You do **NOT** need to install `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. + + Jump to: [top](#)

@@ -446,6 +477,11 @@ 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.

+

+This tool was originally part of a winning entry by Anthony C Howe, but with +some modifications over time, as things have changed. +

+ Jump to: [top](#)
@@ -454,14 +490,15 @@ Jump to: [top](#)

`mkiocccentry(1)` will write two JSON files: `.auth.json` and `.info.json`. These files contain information about the author(s) and about the -submission. These files **MUST** pass the checks of `chkentry(1)`. +submission. These files **MUST** pass the checks of `chkentry(1)`!

-If `chkentry` does not pass and you used `mkiocccentry(1)` it is **possibly** a +If `chkentry` does not pass and you used `mkiocccentry(1)` it is **very likely** a bug and you should [report it as a bug at the mkiocccentry issues page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). -See the FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)". +See the +FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".

@@ -475,7 +512,8 @@ executed. In this case, there should be no problems as `mkiocccentry(1)` should Please see the FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry) for more details on this tool and how you can use it to validate your -`.auth.json` and `.info.json` files. +`.auth.json` and `.info.json` files manually, without having to repackage your +submission.

@@ -504,15 +542,6 @@ page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".

-

-Of course, it is also possible that `mkiocccentry(1)` or one or more of the -tools it calls (or another tool calls) to fail and it is **NOT** a bug. An -example problem is if there is not enough memory available or if some other -library or syscall fails. Nonetheless it might be worth reporting as a bug. It -is a judgement call; if it's a bug it'll be addressed and if it's not that's OK -too. -

-

As part of its sanity checks, `txzchk(1)` will run `fnamchk(1)` on the _filename_ to verify that the name is valid. See the @@ -553,20 +582,26 @@ you wish to.

-To see more details on `fnamchk` and how to manually validate your submission +For more information on `fnamchk` and how to manually validate your submission tarball filename, see the FAQ on "[fnamchk](../faq.html#fnamchk)".

+

+Note that the `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm. +Thus `mkiocccentry(1)` does not directly invoke `fnamchk(1)`, although we will +in the judging process. +

+

-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 +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 expect that everything **IS** OK. +everything checks out OK you should **NOT** assume that everything **IS** OK.

@@ -585,8 +620,35 @@ FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)". As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.

+ +
+# Problems/bugs in tools +
+

-We recommend that you use the [example +Although the tools have been tested quite a bit, and although it is quite +unlikely that there are bugs in it, it is nonetheless possible for bugs to +exist, as all programmers know. In this case, **please** ask for help or report what +you think is a bug as a bug, via the [bug report issues page in the mkiocccentry +repo](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). +

+ +

+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 +bug. An example problem is if there is not enough memory available or if some +other library or syscall fails. Nonetheless it might be worth reporting as a +bug; it is a judgement call; if it's a bug it'll be addressed and if it's not +that's OK too! +

+ + +
+# Makefiles +
+ +

+We **recommend** that you use the [example Makefile](https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example) from the [IOCCC mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), renamed as `Makefile` of course, as the starting point for your submission's @@ -594,7 +656,7 @@ required `Makefile`. Feel free to modify the `Makefile` to suit your obfuscated needs.

-The rest of these guidelines will assume that you are using some variant of the +The rest of this section will assume that you are using some variant of the [example Makefile](https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example), renamed as `Makefile` of course.

@@ -605,13 +667,13 @@ We suggest that you compile your submission with a commonly available

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

It is **OK** 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 `remarks.md` file and adjust your `Makefile` accordingly.

@@ -686,14 +748,15 @@ 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. +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).

-Additionally, some compilers like to warn about certain use of `char *`s which -is not only likely dubious itself 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 +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 +should not worry about this either; this is the warning +`-Wno-unsafe-buffer-usage`. See also the FAQ on "[forced warnings](../faq.html#forced_warnings)" and the FAQ on "[`-Weverything`](../faq.html#weverything)". @@ -709,6 +772,11 @@ reason that is what you intend to happen in which case document that too in your `remarks.md` file. :-)

+

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

+ All other things being equal, a program that must turn off fewer warnings will be considered better, for certain values of better. @@ -718,11 +786,19 @@ try something such as:

``` - CSILENCE= -Wno-some-thing -Wno-another-thing -Wno-unknown-warning-option + CSILENCE= -Wno-some-thing -Wno-another-thing ``` +For instance: + + +``` + CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation +``` + +

-If you do add "`-Wno-some-thing`" to your Makefile, consider changing: +If you do add "`-Wno-foo`" to your Makefile, consider changing: ``` CUNKNOWN= @@ -736,7 +812,8 @@ to:

Some compilers have reported this as an error, however, and if you have -such a compiler you might want to not add it and note it in your `remarks.md`. +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.

@@ -772,6 +849,10 @@ use the `COTHER` Makefile variable. For example: _and_ `clang`** support it.

+

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

+ Jump to: [top](#)