Makefile variable. For example, to use
CSTD= -std=c17
+
+
+
+
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 with debug symbols:
+For example, to compile without optimization, and to include debug symbols:
OPT= -O0 -g3
+
+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
@@ -1046,9 +1079,14 @@ 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, as detailed below.
+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.
-Disabling warnings
There is no real penalty for compiler warnings. Sometimes
compiler warnings cannot be helped: especially in the case of
@@ -1078,17 +1116,19 @@ not meeting your claims).
On the other hand, some warnings cannot be disabled and are enabled by compilers
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 (see below for an example).
+about this, though it might be worth pointing out.
-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
--Wunsafe-buffer-usage and the way to disable it is -Wno-unsafe-buffer-usage. See also the
+For instance, some compilers like to warn about use of char *s, 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. :-)
@@ -1110,17 +1150,23 @@ To turn off a compiler warning, in your submission’s Makefile,
try something such as:
CSILENCE= -Wno-some-thing -Wno-another-thing
-For instance:
+
+For instance:
+
CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation
-
If you do add “-Wno-foo” to your Makefile, consider changing:
+If you do add “-Wno-foo” to your Makefile, consider changing:
+
CUNKNOWN=
-to:
+
+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 the OS, OS version and compiler that this shows up.
+remarks.md which OS, OS version, compiler and compiler version you had the
+problem.
Defining macros in the Makefile
diff --git a/next/guidelines.md b/next/guidelines.md
index 5078c1d0b..41cd8435e 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -14,7 +14,9 @@ as well as our
FAQ on "[asking questions](../faq.html#question)"
about these guidelines. You might also find the
FAQ in general useful, especially the
-[FAQ section "How to enter: the bare minimum you need to know"](../faq.html#submit).
+FAQ section "[How to enter: the bare minimum you need to know"](../faq.html#submit)"
+and the
+FAQ section "[Entering the IOCCC: more help and details](../faq.html#submitting_help)".
# The IOCCC is closed
@@ -52,7 +54,7 @@ Jump to: [top](#)
-These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-05**.
+These [IOCCC guidelines](guidelines.html) are version **28.26 2024-12-06**.
**IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -60,7 +62,7 @@ These [IOCCC guidelines](guidelines.html) are version **28.25 2024-12-05**.
Jump to: [top](#)
-## Change marks
+# Change marks
**← Lines that start with this symbol indicate a change from the
@@ -329,11 +331,10 @@ value similar to the [2001-2012](../faq.html#size_rule2001-2012) and
[2013-2020](../faq.html#size_rule2013-2020) IOCCC eras.
-
Jump to: [top](#)
-## `mkiocccentry`
+# `mkiocccentry`
@@ -364,25 +365,26 @@ compressed tarball **will not be formed**. For instance, if `chkentry(1)` (see
below) fails to validate the `.auth.json` or `.info.json`
[JSON](https://www.json.org/json-en.html) files that `mkiocccentry(1)` creates,
it is an error and **possibly** a bug that you should [report as a bug at the
-mkiocccentry issues
+mkiocccentry bug report
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E).
**PLEASE run the `bug_report.sh` script to help us out here!** See the
FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
-If you want to know what `.auth.json` is, see the FAQ on
-"[.auth.json](../faq.html#auth_json)". If you want to know what the
-`.info.json` file is, see the FAQ on "[.info.json](../faq.html#info_json)". On
-the other hand, if you want to know a bit more details about `chkentry`, see the
+If you want to know what `.auth.json` is, see the
+FAQ on "[.auth.json](../faq.html#auth_json)".
+If you want to know what the `.info.json` file is, see the
+FAQ on "[.info.json](../faq.html#info_json)".
+On the other hand, if you want to know a bit more details about `chkentry`, see the
FAQ about "[chkentry](../faq.html#chkentry)".
-However, just because there are errors **does not** mean it is a bug in the
-code. It might be an issue with your submission. Thus if you report an error as
-a bug it might not be something that will be fixed as there might not be
-anything wrong.
+However, even if `mkiocccentry` or one of the tools it invokes reports an error,
+**does not** necessarily mean it is a bug in the code. It might be an issue with
+your submission. Thus if you report an error as a bug it might not be something
+that will be fixed as there might not be anything wrong with the tools.
@@ -424,73 +426,32 @@ overwrites the file).
See the
FAQ on "[mkiocccentry](../faq.html#mkiocccentry)"
-for how to use this tool in more detail.
+for how to use this tool, in more detail.
-
-Below are the tools that `mkiocccentry(1)` will run.
-
+
+
+# mkiocccentry tools
+
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.
+execute one or more additional tools.
-
-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!
-
-
-
-You do **NOT need to install** `jparse` from the [jparse
-repo](https://github.com/xexyl/jparse)! The `mkiocccentry` tools link in the
-static library from the `mkiocccentry` clone. This also goes for the
-[dbg](https://github.com/lcn2/dbg) and
-[dyn_array](https://github.com/lcn2/dyn_array) libraries that the tools use.
-
-
-
-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.
-
-
-
-Jump to: [top](#)
-
## `iocccsize`
-`mkiocccentry(1)` will use code from `iocccsize(1)` which
+
+`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 `mkiocccentry`, we will not include it
-here again.
In other words, you no longer need to run `iocccsize` manually.
-
-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.
-
-
Jump to: [top](#)
@@ -512,8 +473,8 @@ FAQ on "[reporting mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
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
+`.info.json`, then the tarball will be formed and then `txzchk(1)` will be
+executed on it. In this case, there should be no problems, as `mkiocccentry(1)` should
**NOT** form a tarball if there are any issues.
@@ -524,6 +485,47 @@ files, then unless it is a system specific problem, it is likely a bug in
unlikely.
+
+`chkentry` uses the `jparse` library. See the
+[jparse
+README.md](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md)
+in the [mkiocccentry GitHub repo subdirectory
+jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse) as well as
+the [jparse library README.md
+file](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/jparse_library_README.md)
+in the [mkiocccentry GitHub repo subdirectory
+jparse](https://github.com/ioccc-src/mkiocccentry/tree/master/jparse), for more
+details.
+
+
+
+The `jparse` parser, library and tools were co-developed by
+[Cody Boone Ferguson](../authors.html#Cody_Boone_Ferguson) and
+[Landon Curt Noll](http://www.isthe.com/chongo/index.html) in 2022 and comes
+from the [jparse repo](https://github.com/xexyl/jparse). However, the
+**mkiocccentry tools use a _clone_** of the [jparse
+repo](https://github.com/xexyl/jparse) **at a _specific_ release**.
+Thus the `mkiocccentry` will at times be behind the
+[jparse repo](https://github.com/xexyl/jparse)!
+
+
+
+You do **NOT need to install** `jparse` from the [jparse
+repo](https://github.com/xexyl/jparse)! The `mkiocccentry` tools link in the
+static library from `mkiocccentry`'s clone itself. This also goes for the
+[dbg](https://github.com/lcn2/dbg) and
+[dyn_array](https://github.com/lcn2/dyn_array) libraries that the `mkiocccentry`
+tools, the `dyn_array` library uses and the `jparse` library uses.
+
+
+
+In other words, `mkiocccentry` **contains everything** you need, and _even if you
+do install_ the libraries from their respective repos, it/they will **not be
+used** when compiling the `mkiocccentry` tools. This is important to
+make sure that you're using the correct versions, which is verified by
+`chkentry`.
+
+
Please see the
FAQ on "[validating .auth.json and/or .info.json files](../faq.html#chkentry)
@@ -540,7 +542,6 @@ FAQ on "[.info.json](../faq.html#info_json)"
for much more information on these files.
-
Jump to: [top](#)
@@ -552,7 +553,7 @@ Jump to: [top](#)
compressed tarball; if any issues are found ('`feathers are stuck in the
tarball`' :-) ) **AND if and _ONLY IF_ you used
`mkiocccentry(1)`**, then it is **possibly** a bug in one of the tools and you
-might want to [report it as a bug at the mkiocccentry issues
+might want to [report it as a bug at the mkiocccentry bug report
page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). **PLEASE run the
`bug_report.sh` script to help us out here!** See the
FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
@@ -567,7 +568,7 @@ and [fnamchk below](#fnamchk) for more details on this tool.
It is beyond the scope of this document to discuss the many tests that
-`txzchk(1)` do. In this case we refer you to the [source
+`txzchk(1)` performs; if you wish to know, we refer you to the [source
code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c) or the man
page. You might find a fun option if you do either of these!
@@ -590,10 +591,10 @@ Jump to: [top](#)
-A tool that [txzchk](#txzchk) runs is `fnamchk`. This is an important part of
-its algorithm. If the filename is incorrect (or the filename does not match the
+As an important part of its algorithm, [txzchk](#txzchk) directly executes `fnamchk`.
+If the filename is invalid (or the filename does not match the
directory name of the tarball) then it is an **error** and you risk violating
-[Rule 17](rules.html#rule17). Nevertheless, you can run the tool manually should
+[Rule 17](rules.html#rule17). Nevertheless, you can run the tool manually, should
you wish to.
@@ -604,22 +605,11 @@ 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
+Because `txzchk(1)` tool uses `fnamchk(1)` tool as part of its algorithm,
+`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
-problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
-file, the `mkiocccentry(1)` tool would not package it. But if you were to package
-it manually, you would be violating [Rule 17](rules.html#rule17). But even if
-everything checks out OK you should **NOT** assume that everything **IS** OK.
-
-
It is extremely unlikely that `fnamchk(1)` reporting an invalid filename is a
bug in `fnamchk(1)` and as such, ignoring such an issue risks violating [Rule
@@ -633,7 +623,13 @@ FAQ on "[report mkiocccentry bugs](../faq.html#mkiocccentry_bugs)".
-As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**.
+As you can see, the use of `mkiocccentry(1)` is **HIGHLY RECOMMENDED**, and at
+the risk of stating the obvious, you run **a VERY BIG risk** of having
+your submission rejected if you package your own tarball, and there are **ANY
+problems**. For instance, if `chkentry(1)` found a problem in your `.info.json`
+file, the `mkiocccentry(1)` tool would not package it. But if you were to package
+it manually, you would be violating [Rule 17](rules.html#rule17). But even if
+everything checks out OK you should **NOT** assume that everything **IS** OK.
@@ -651,10 +647,10 @@ repo](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug
Of course, it is also possible for `mkiocccentry(1)`, or one or more of the
-tools it executes (or another tool executes), to fail, and **NOT** because of a
+tools it executes (or another tool executes), to fail, but **NOT** because of a
bug. An example problem is if there is not enough memory available or if some
other library or syscall fails. Nonetheless it might be worth reporting as a
-bug; it is a judgement call; if it's a bug it'll be addressed and if it's not
+bug; it is a judgement call: if it's a bug it'll be addressed and if it's not
that's OK too!
@@ -677,10 +673,16 @@ Makefile](%%REPO_URL%%/next/Makefile.example)
download="Makefile">download example Makefile
-Feel free to modify the `Makefile` to suit your obfuscated
+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`.
@@ -691,26 +693,30 @@ We suggest that you compile your submission with a commonly available
`-std=gnu17` (ISO C 2017 with GNU extensions) C compiler.
+
## 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 -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** if you need to require your submission to **not be** compiled
+It **is OK** if you need to require your submission to **NOT be** compiled
using the default `-std=gnu17 -O3 -g3` settings. Simply **explain why**
-your submission should not be compiled using `-std=gnu17 -O3 -g3` in
-your `remarks.md` file **and** adjust your `Makefile` accordingly.
+your submission should NOT be compiled using `-std=gnu17 -O3 -g3` in
+your `remarks.md` file, **AND** adjust your `Makefile` accordingly.
-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`.
+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.
@@ -745,13 +751,21 @@ by modifying the `CSTD` Makefile variable. For example, to use `c17` instead:
```
+
+
+
+
## 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 with debug symbols:
+For example, to compile without optimization, and to include debug symbols:
```
@@ -759,8 +773,30 @@ For example, to compile without optimization and with debug symbols:
```
+
+
+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,
@@ -775,12 +811,15 @@ 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, as detailed below.
+options anyway, as detailed below. See the
+FAQ on "[-Weverything](../faq.html#weverything)"
+for more details.
-
-## Disabling warnings
-
+
+If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further
+modified.
+
There is no real penalty for compiler warnings. Sometimes
@@ -818,19 +857,23 @@ not meeting your claims).
On the other hand, some warnings cannot be disabled and are enabled by compilers
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 (see below for an example).
+about this, though it might be worth pointing out.
-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
-`-Wunsafe-buffer-usage` and the way to disable it is `-Wno-unsafe-buffer-usage`. See also the
+For instance, some compilers like to warn about use of `char *`s, 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
@@ -860,22 +903,25 @@ 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
@@ -884,7 +930,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, or at least note in your
-`remarks.md` the OS, OS version and compiler that this shows up.
+`remarks.md` which OS, OS version, compiler and compiler version you had the
+problem.