In general, unless you have a fix, if you want to report something, you should instead first look at the IOCCC
issues to see if the
diff --git a/contact.md b/contact.md
index 555f0396c..d33f36c78 100644
--- a/contact.md
+++ b/contact.md
@@ -20,11 +20,11 @@ FAQ on "[submitting a pull request](faq.html#pull_request)".
If you are trying to:
* **Report a bug in an IOCCC winning entry** - See our
-FAQ on "[report entry bug](faq.html#report_bug)"
+FAQ on "[reporting an entry bug](faq.html#report_bug)"
* **Report an IOCCC website problem** - See our
-FAQ on "[report website problem](faq.html#report_web_problem)"
+FAQ on "[reporting a website problem](faq.html#report_web_problem)"
* **Report a broken or wrong web link** - See our
-FAQ on "[report broken link](faq.html#fix_link)"
+FAQ on "[reporting a broken link](faq.html#fix_link)"
In general, unless you have a fix, if you want to report something, you should instead first look at the [IOCCC
issues](https://github.com/ioccc-src/winner/issues) to see if the
diff --git a/faq.html b/faq.html
index 6af4dd737..689213674 100644
--- a/faq.html
+++ b/faq.html
@@ -425,7 +425,7 @@
-- Q 3.0: What sort of checks does the mkiocccentry tool perform?
+- Q 3.0: What is the
mkiocccentry(1) process and what sort of checks does it perform?
- Q 3.1: How can I validate my submission tarball?
- Q 3.2: What is the
fnamchk tool?
- Q 3.3: How can I validate my
.auth.json and/or .info.json files?
@@ -628,10 +629,12 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
limit_ioccc.h
as MAX_FILE_COUNT) and other information about your submission,
-information about the author (or authors), and then it runs a lot of tests before (if
-all is OK) forming your tarball. After this is done it will additionally run the
-txzchk(1) tool (which runs the fnamchk(1) tool) on the submission tarball.
-The tool chkentry(1) will also be run, before creating the tarball. See the
+information about the author (or authors), and then it runs a lot of tests.
+If everything is OK, it will write the required .auth.json and .info.json
+files, checking each with chkentry(1) and then, if all is OK, it will create
+the tarball. After the tarball is formed, it will run txzchk(1) on it, which
+runs fnamchk(1). If all is OK, your submission tarball should be good to go.
+Please see
FAQ on “txzchk”,
the
FAQ on “fnamchk”
@@ -694,6 +697,16 @@ directory will be created, with the name based on your IOCCC registrati
username, which is in the form of a UUID, and submission number; see the
rules for more details on this, and in particular Rule
17.
+IMPORTANT NOTE: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools then you will have to specify the options for the tools that
+are required like chkentry(1), txzchk(1) and fnamchk(1). But even if you
+have installed them but some tools are out of date (in the install path) it will
+cause problems. Additionally, if you do not have the most recent version when
+submitting a tarball it will be rejected for not having the right versions of
+the tools. This is why you MUST make sure you have the most recent version
+of all the tools and you either run it from the repo directory itself OR you
+install them (make install as via sudo or as root).
If the subdirectory in the work directory (based on your submit ID and
slot number) already exists, you will have to
move it, remove it or otherwise specify a different work directory (NOT the
@@ -701,12 +714,12 @@ subdirectory), as it needs to be empty.
This subdirectory is where your files will be copied to. Your submission
tarball (which you will upload to the submit server) that txzchk(1) will
validate will be placed in the work directory, and its contents will
-be the subdirectory with your submission’s files.
-The mkiocccentry(1) tool will ask you for information about your
+be the subdirectory with your submission’s files.
+The mkiocccentry(1) tool will also ask you for information about your
submission as well as author details (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-“finer details” section.
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the “finer
+details” section.
See also the
mkiocccentry repo FAQ
for more up to date information on downloading, compiling, and related FAQ information.
@@ -797,27 +810,36 @@ the one linked to above.
-First, PLEASE read the IOCCC markdown guidelines.
+PLEASE look at the template remarks.md to give you a better idea of how
+it should be formed, as it has some instructions you should follow:
+
+PLEASE pay especial attention to the instructions, including the IOCCC
+markdown guidelines. You will observe that it links back to this
+FAQ as to what you should or should not say.
Next, while you may put in as much or as little as you wish into your entry’s
remarks.md file, we do have few important suggestions:
-We recommend that you explain how to use your entry. Explain the
+
We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.
-We highly recommend that you explain why you think your entry is
+
We highly recommend that you explain why you think your submission is
well obfuscated.
For those submissions that win the IOCCC, we often use much of text from the
remarks.md file in the Author’s remarks section of the index.html file.
For this reason, a well written remarks.md file is considered a plus.
While not required, consider adding bit of humor to your remarks.md
-as most people who are not humor impaired, as well as the IOCCC judges
-appreciate the opportunity for a fun read as well as a chuckle or two.
+as most people who are not humor impaired, as well as the IOCCC judges (who
+might or might not be humour impaired :-) ), appreciate the opportunity for a
+fun read as well as a chuckle or two.
What helps:
-- explaining what your entry does
-- how to entice it to do what it is supposed to do
-- what obfuscations are used
-- what are the limitations of your entry in respect of portability and/or input data
-- how it works (if you are really condescending)
+- explaining what your entry does.
+- how to entice it to do what it is supposed to do.
+- what obfuscations are used.
+- what are the limitations of your entry in respect of portability and/or input data.
+- how it works (if you are really condescending).
What does not help:
@@ -829,11 +851,13 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
guidelines AND rules if this is not clear!
-- leaving the remark section empty.
+- leaving the remark section empty (which would also indicate that you did not
+use
mkiocccentry(1), as it requires it to not be of size 0, though if you only
+include whitespace you would still be violating Rule 17).
Jump to: top
-
Q 0.5 What should I do with the try.sh and try.alt.sh scripts?
+Q 0.5: What should I do with the try.sh and try.alt.sh scripts?
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
@@ -858,6 +882,22 @@ but we do enjoy interesting and creative uses of submissions.
example Makefile that you modify for your submission. See the
FAQ on “submission Makefiles.
Jump to: top
+
+
Q 0.6: What permissions may my files be and what if I need different permissions?
+
+As Rule 17 states, files in your submission tarball MUST be
+specific permissions. In particular: directories MUST be drwxr-xr-x (i.e.
+0755), the optional files, try.sh or try.alt.sh, if provided, MUST be
+-r-xr-xr-x (i.e. 0555) and all other files MUST be -r--r--r-- (i.e.
+0444).
+If you need a file to be executable, say a script, then make sure you do so in
+the appropriate place in your Makefile. See the
+FAQ on “submission Makefile”
+for more details.
+Do remember that if your submission requires different filenames, then you
+MUST make a COPY of them in your Makefile. See also Rule
+11.
+Jump to: top
@@ -1349,34 +1389,189 @@ entries that do not win on their web page for everyone to see.
Section 3: The mkiocccentry toolkit: finer details
Jump to: top
-
-
Q 3.0: What sort of checks does the mkiocccentry tool perform?
+
+
Q 3.0: What is the mkiocccentry(1) process and what sort of checks does it perform?
-
mkiocccentry(1) will check and warn about the following conditions:
+
In full, the mkiocccentry(1) tool performs the following steps:
+
+- Ask the user for a submission ID (see the how to register
+for more details on how to obtain this and Rule 17 for
+the importance of this).
+
+- If this is an invalid UUID (malformed), you will be asked to correct it
+until it is.
+
+- Ask the user for the submission slot (the submission number; see how to
+register and Rule 17 for more details).
+
+- If this is out of range (see
MAX_SUBMIT_SLOT in
+limit_ioccc.h)
+and you will be asked to correct it until it is.
+
+- Make the submission directory under
topdir in the form of
+workdir/submit.USERNAME-SLOT.TIMESTAMP (the timestamp is calculated by
+mkiocccentry(1) so you do not have to worry about this).
+
+- If this directory already exists it is an error.
+
+- Change to the
topdir.
+- Traverse the directory, creating lists of ignored/forbidden
+files/directories/symlinks as well as a list directories to make and a list of
+files to copy to the submission directory (and if (sub)directories are found
+with files, copy those files to their respective directory). Note the following:
+
+- If the depth is too deep it is an error (see
MAX_PATH_DEPTH in
+limit_ioccc.h).
+- If there are too many extra directories (total count not including the
+submission directory itself, unrelated to
MAX_PATH_DEPTH above) it is an
+error (see MAX_EXTRA_DIR_COUNT in
+limit_ioccc.h).
+- If the max path length is <= 0 it is an error (and a bug).
+- If the max depth is <= 0 it is an error (and a bug).
+- If the max filename length is <= 0 it is an error (and a bug).
+- If a path is NULL it is an error.
+- If a path is an empty string it is an error.
+- If the path length (i.e.
strlen(path) where path starts after the
+initial ./ of the path in the topdir) is too long it is an error (see MAX_PATH_LEN in
+limit_ioccc.h).
+- If a filename (last component of the path) is too long it is an error (see
MAX_FILENAME_LEN in
+limit_ioccc.h).
+- If a filename or directory name is not a sane relative path, not allowed
+or will not be added for some other reason, it will be added to a relevant list to show to
+the user later, to let them know it will not be added to the submission. By
relative we mean it
+must not start with / (which shouldn’t happen even if you give an absolute
+path) and by sane we mean that each component must match the regexp: ^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$.
+- If a directory is unreadable it is an error.
+- If a directory causes a cycle in the tree it is an error.
+- If
stat(2) on the path fails it is an error.
+- If
prog.c, Makefile or remarks.md is/are not found it is an error.
+- If too many files that are not
prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh are found, it is an error (see
+MAX_EXTRA_FILE_COUNT in
+limit_ioccc.h).
+- Symlinks are not allowed but it is not an error (they will be added to a
+list and ignored).
+- If any file type other than a regular file, a directory or a symlink is
+encountered it is an error.
+- If there is an unknown error it is an error :-)
+
+- Show each list to the user, asking if this is okay. The lists include:
+
+- Ignored directories (those like
.git, CVS, RCCS and .svn).
+- Unsafe directory names that will not be added (i.e. those that are not
+POSIX plus + safe chars only; see above step (4)). This includes directories
+starting with a
..
+- Forbidden files such as
index.html, README.md, prog, prog.alt.
+- Unsafe filenames that will not be added (i.e. those that are not POSIX
+plus + safe chars only; see above step (4)). This includes files starting
+with
..
+- Symlinks found (these are not allowed).
+- Directories to be made.
+- Required files (
prog.c, Makefile and remarks.md) to be copied.
+- Non-required files to be copied.
+- The user is asked to verify each list, including the lists of directories
+and files to be made/copied, and if the user says it is not OK the program will abort.
+
+- Make any directories if necessary (under
+
workdir/submit.USERNAME-SLOT.TIMESTAMP i.e. the submission directory).
+
+- Directories MUST be and are made with mode
0755.
+- If any directory is not this mode
txzchk(1) will flag it.
+
+- The non-ignored files are copied to their respective directories under the
+submission directory.
+
+try.sh and try.alt.sh MUST be and are copied as mode 0555.- All other files MUST be and are copied as mode
0444.
+- Anything else will be flagged by
txzchk(1).
+
+cd submit.USERNAME-SLOT.TIMESTAMP (i.e. switch to submission directory).make -f Makefile clobber.
+
+- If this fails it is not an error but you are warned about it (it is an error only if the
Makefile
+does not exist); even so, see Rule 20.
+
- Traverse the new tree from
. with additional steps from (4).
+
+- If any file has an ignored directory name in it, it is an error.
+- If a symlink is found it is an error.
+- If any file type other than a directory or regular file exists it is an
+error.
+- If a forbidden filename exists it is an error.
+- If any file or directory starts with
/ or is not POSIX plus + safe chars
+only (see (4) above) it is an error.
+- If the depth is too deep it is an error.
+- If
prog.c, Makefile or remarks.md are missing (or not readable
+regular files) it is an error.
+iocccsize(1) (via the mkiocccentry(1) function check_prog_c()) will
+be run on your prog.c, allowing you to override any warnings; if you do not
+override an issue flagged it is an error but if warnings from check_prog_c()
+are ignored you risk violating the Rules, including Rule
+2.check_Makefile() will be run on Makefile; if it is a non-readable or
+empty file it is an error but otherwise you may override any warnings
+(risking violating the Rules, especially Rule
+17 and Rule 20).check_remarks_md() will be run on your remarks.m; if it is not a
+regular readable file or it is empty it is an error. Otherwise it will
+proceed. Note it does not check that there is any text in the file, just
+that the file size is not 0, and having a remarks.md that is not size 0
+but has no content is violating Rule 17 and Rule
+19.- If any other error condition from step (4) occurs it is also an error.
+
+- Report on any directories that were made and files that were copied in (7)
+but are now gone: asking the user to verify.
+- Present the list of non-dot files that remain and ask the user to confirm.
+- Ask the user for a submission title.
+- Ask the user for a one line abstract of the submission.
+- Ask the user for the number of authors and for each author ask a variety of
+questions (see below for more information on what kind of questions).
+- Show the output of
ls -lakR ., asking the user to confirm that the listing
+is okay.
+- Create
.info.json and run chkentry(1) on it.
+
+- If
chkentry(1) fails to validate the file make sure that you have
+obtained and compiled the latest version of all the tools and you either are
+in the repo’s directory, you pass the options to give the path to the tools
+or you have installed the latest tools!
+
+- Create
.auth.json and run chkentry(1) on it.
+
+- If
chkentry(1) fails to validate the file make sure that you have
+obtained and compiled the latest version of all the tools and you either are
+in the repo’s directory, you pass the options to give the path to the tools
+or you have installed the latest tools!
+
+- Create the tarball.
+- Run
txzchk(1) on the tarball.
+
+
If any of the steps fail or if the user says something is not okay, it aborts.
+Some of the other checks that are made:
-- If the files do not exist, are not regular files or cannot be read.
- If
prog.c violates Rule 2 (see
iocccsize.c).
-- If
prog.c is empty.
-- If
prog.c has any high bit char (see
-iocccsize.c).
-- If
prog.c has any NUL char (see
-iocccsize.c).
+- If
prog.c is empty (see Rule 1 and the
+Guidelines).
+- If
prog.c has any NUL (\0) char (see
+rule_count.c).
- If
prog.c has any unknown or invalid trigraph (see
-iocccsize.c).
+rule_count.c).
- If
prog.c triggers a word buffer overflow (see
-iocccsize.c).
+rule_count.c).
- If
prog.c triggers an ungetc(3) error (see
-iocccsize.c).
+rule_count.c).
- If the first rule in the
Makefile is not all.
- If the
Makefile does not have a clean rule.
- If the
Makefile does not have a clobber rule.
- If the
Makefile does not have a try rule.
-- If the
remarks.md is empty.
-
Conditions that one must correct, and which mkiocccentry(1) will prompt until
+
Conditions that one MUST correct, and which mkiocccentry(1) will prompt until
they are correct, are:
+- Your contest ID is invalidly formed.
+- Your submit slot is < 0 or >
MAX_SUBMIT_SLOT (see
+limit_ioccc.h).
- Your title is not in the range of 1 through
MAX_TITLE_LEN chars (see
limit_ioccc.h).
- Your title does not match the regexp
^[0-9a-z][0-9a-z._+-]*$.
@@ -1387,8 +1582,7 @@ they are correct, are:
- An author name is not 1 through
MAX_NAME_LEN chars (see
limit_ioccc.h).
- Duplicate author name.
-- Country code is invalid (not ISO 3166-1 2 character
-codes).
+- Country code is invalid (i.e. it is not a ISO 3166-1 2 character code).
- An email, if provided, is not in the format of
x@y or
if x or y contain a @, are empty or if the total length is longer than
MAX_EMAIL_LEN (see limit_ioccc.h).
@@ -1398,18 +1592,20 @@ or https:// or is longer than MAX_URL_LEN chars (see
or does not have anything after the http:// or https://.
- A mastodon handle, if provided, is not in the form of
@user@site (i.e. starts with an @, has text following it and then another
-@ followed by more text and has no other @) or is longer than MAX_MASTODON_LEN (see
+@ followed by more text and has no other @), or if it is longer than MAX_MASTODON_LEN (see
limit_ioccc.h).
- A GitHub account, if provided, does not start with an
@,
-has more than one @ or is longer than MAX_GITHUB_LEN (see
+has more than one @, does not have any text after the @ or is longer than MAX_GITHUB_LEN (see
limit_ioccc.h).
- An affiliation, if provided, is longer than
MAX_AFFILIATION_LEN (see limit_ioccc.h).
- An author handle, if the default is not accepted, does
not match the regexp
^[0-9A-Za-z][0-9A-Za-z._+-]*$.
- An author handle is repeated.
-- The output of
ls on the submission directory is incorrect.
+
The program does confirm that the information for each author is correct,
+allowing you to correct the information without having to start the program
+over.
Although the mkiocccentry(1) tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
rules state, each of these tools has a -h option.
@@ -1428,8 +1624,12 @@ FAQ on “
fnamchk”
for more details on the tools that
mkiocccentry either executes directly or
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
+
See also the
+FAQ on “how to test everything at once without having to answer
+questions”.
See also the Guidelines and the Rules
-(and in particular Rule 17).
+(especially
Rule 1,
Rule 2,
Rule
+17,
Rule 19 and
Rule 20).
Jump to: top
diff --git a/faq.md b/faq.md
index f12383137..b23bb52fc 100644
--- a/faq.md
+++ b/faq.md
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents
-This is FAQ version **28.2.2 2025-01-30**.
+This is FAQ version **28.2.8 2025-02-10**.
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
@@ -14,6 +14,7 @@ This is FAQ version **28.2.2 2025-01-30**.
- **Q 0.3**:
What should I put in my submission Makefile?
- **Q 0.4**:
What should I put in the remarks.md file of my submission?
- **Q 0.5**:
What should I do with the `try.sh` and `try.alt.sh` scripts?
+- **Q 0.6**:
What permissions may my files be and what if I need different permissions?
## 1. [Entering the IOCCC: more help and details](#submitting_help)
@@ -41,7 +42,7 @@ This is FAQ version **28.2.2 2025-01-30**.
## 3. [The mkiocccentry toolkit: finer details](#mkiocccentry_details)
-- **Q 3.0**:
What sort of checks does the mkiocccentry tool perform?
+- **Q 3.0**:
What is the `mkiocccentry(1)` process and what sort of checks does it perform?
- **Q 3.1**:
How can I validate my submission tarball?
- **Q 3.2**:
What is the `fnamchk` tool?
- **Q 3.3**:
How can I validate my `.auth.json` and/or `.info.json` files?
@@ -217,10 +218,14 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
to a maximum, including the mandatory files, defined in
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
as `MAX_FILE_COUNT`) and other information about your submission,
-information about the author (or authors), and then it runs a lot of tests before (if
-all is OK) forming your tarball. After this is done it will additionally run the
-`txzchk(1)` tool (which runs the `fnamchk(1)` tool) on the submission tarball.
-The tool `chkentry(1)` will also be run, before creating the tarball. See the
+information about the author (or authors), and then it runs a lot of tests.
+
+If everything is OK, it will write the required `.auth.json` and `.info.json`
+files, checking each with `chkentry(1)` and then, if all is OK, it will create
+the tarball. After the tarball is formed, it will run `txzchk(1)` on it, which
+runs `fnamchk(1)`. If all is OK, your submission tarball should be good to go.
+
+Please see
FAQ on "[txzchk](#txzchk)",
the
FAQ on "[fnamchk](#fnamchk)"
@@ -314,6 +319,17 @@ username, which is **in the form of a UUID**, and submission number; see the
[rules](next/rules.html) for more details on this, and in particular [Rule
17](next/rules.html#rule17).
+**IMPORTANT NOTE**: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools then you will have to specify the options for the tools that
+are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
+have installed them but some tools are out of date (in the install path) it will
+cause problems. Additionally, if you do not have the most recent version when
+submitting a tarball it will be rejected for not having the right versions of
+the tools. This is why you **MUST** make sure you have the most recent version
+of all the tools and you either run it from the repo directory itself OR you
+install them (`make install` as via `sudo` or as root).
+
If the **_subdirectory_ in the _work directory_** (based on your submit ID and
slot number) already exists, you will have to
move it, remove it or otherwise specify a different work directory (**NOT** the
@@ -323,12 +339,11 @@ This _subdirectory is where your files will be **copied** to_. Your _submission
tarball_ (which you will upload to the submit server) that `txzchk(1)` will
validate _will be placed in the **work directory**_, and **its _contents_ will
be the _subdirectory_ with your submission's files**.
-
-The `mkiocccentry(1)` tool will ask you for information about your
+The `mkiocccentry(1)` tool will also ask you for information about your
submission _as well as author details_ (that will only be looked at if the
-submission wins), run some tests and run a number of other tools, as briefly
-mentioned earlier, and as described in the
-"[finer details](#mkiocccentry_details)" section.
+submission wins), run some tests and run a number of other tools, as
+mentioned above, and as described in the "[finer
+details](#mkiocccentry_details)" section.
See also the
[mkiocccentry repo FAQ](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md)
@@ -431,16 +446,24 @@ Jump to: [top](#)
-First, **PLEASE** read the [IOCCC markdown guidelines](markdown.html).
+**PLEASE** look at the template remarks.md to give you a better idea of how
+it should be formed, as it has some instructions you should follow:
+
+- [view template remarks.md](%%REPO_URL%%/next/remarks.example.md)
+- [remarks.md template](next/remarks.example.md)
+
+**PLEASE** pay especial attention to the instructions, including the [IOCCC
+markdown guidelines](markdown.html). You will observe that it links back to this
+FAQ as to what you should or should not say.
Next, while you may put in as much or as little as you wish into your entry's
`remarks.md` file, we do have few important suggestions:
-We recommend that you explain how to use your entry. Explain the
+We recommend that you explain how to use your submission. Explain the
command line (if any command line options and arguments are used)
and any input or actions if applicable.
-We highly recommend that you explain why you think your entry is
+We highly recommend that you explain why you think your submission is
well obfuscated.
For those submissions that win the IOCCC, we often use much of text from the
@@ -448,17 +471,18 @@ For those submissions that win the IOCCC, we often use much of text from the
For this reason, a well written `remarks.md` file is considered a plus.
While not required, consider adding bit of humor to your `remarks.md`
-as most people who are not humor impaired, as well as the IOCCC judges
-appreciate the opportunity for a fun read as well as a chuckle or two.
+as most people who are not humor impaired, as well as the IOCCC judges (who
+might or might not be humour impaired :-) ), appreciate the opportunity for a
+fun read as well as a chuckle or two.
#### What helps:
-- explaining what your entry does
-- how to entice it to do what it is supposed to do
-- what obfuscations are used
-- what are the limitations of your entry in respect of portability and/or input data
-- how it works (if you are really condescending)
+- explaining what your entry does.
+- how to entice it to do what it is supposed to do.
+- what obfuscations are used.
+- what are the limitations of your entry in respect of portability and/or input data.
+- how it works (if you are really condescending).
#### What does not help:
@@ -471,13 +495,15 @@ it, not very obfuscated entries have a minuscule chance to win (although
in the C code for that matter) - we like to be unbiased during the judging
rounds; we look at the author name only if an entry wins. See the
[guidelines](next/guidelines.html) **AND** [rules](next/rules.html) if this is not clear!
-- leaving the remark section empty.
+- leaving the remark section empty (which would also indicate that you did not
+use `mkiocccentry(1)`, as it requires it to not be of size 0, though if you only
+include whitespace you would still be violating [Rule 17](next/rules.html#rule17)).
Jump to: [top](#)
-### Q 0.5 What should I do with the `try.sh` and `try.alt.sh` scripts?
+### Q 0.5: What should I do with the `try.sh` and `try.alt.sh` scripts?
If your submission has more than one use, or if you have interesting ways to
@@ -510,6 +536,30 @@ FAQ on "[submission Makefiles](#makefile).
Jump to: [top](#)
+
+
+
+### Q 0.6: What permissions may my files be and what if I need different permissions?
+
+
+As [Rule 17](#rule17) states, files in your submission tarball **MUST** be
+specific permissions. In particular: directories **MUST** be `drwxr-xr-x` (i.e.
+`0755`), the optional files, `try.sh` or `try.alt.sh`, if provided, **MUST** be
+`-r-xr-xr-x` (i.e. `0555`) and all other files **MUST** be `-r--r--r--` (i.e.
+`0444`).
+
+If you need a file to be executable, say a script, then make sure you do so in
+the appropriate place in your Makefile. See the
+FAQ on "[submission Makefile](#makefile)"
+for more details.
+
+Do remember that if your submission requires different filenames, then you
+**MUST** make a **COPY** of them in your `Makefile`. See also [Rule
+11](next/rules.html#rule11).
+
+
+
+Jump to: [top](#)
@@ -1158,35 +1208,169 @@ Jump to: [top](#)
Jump to: [top](#)
-
-### Q 3.0: What sort of checks does the mkiocccentry tool perform?
+
+### Q 3.0: What is the `mkiocccentry(1)` process and what sort of checks does it perform?
-`mkiocccentry(1)` will check and warn about the following conditions:
+In full, the `mkiocccentry(1)` tool performs the following steps:
+
+0. Ask the user for a submission ID (see the [how to register](next/register.html)
+for more details on how to obtain this and [Rule 17](next/rules.html#rule17) for
+the importance of this).
+ * If this is an invalid UUID (malformed), you will be asked to correct it
+ until it is.
+1. Ask the user for the submission slot (the submission number; see [how to
+register](next/register.html) and [Rule 17](next/rules.html#rule17) for more details).
+ * If this is out of range (see `MAX_SUBMIT_SLOT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h))
+ and you will be asked to correct it until it is.
+2. Make the submission directory under `topdir` in the form of
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` (the timestamp is calculated by
+`mkiocccentry(1)` so you do not have to worry about this).
+ * If this directory already exists it is an error.
+3. Change to the `topdir`.
+4. Traverse the directory, creating lists of ignored/forbidden
+files/directories/symlinks as well as a list directories to make and a list of
+files to copy to the submission directory (and if (sub)directories are found
+with files, copy those files to their respective directory). Note the following:
+ * If the depth is too deep it is an error (see `MAX_PATH_DEPTH` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If there are too many extra directories (total count not including the
+ submission directory itself, unrelated to `MAX_PATH_DEPTH` above) it is an
+ error (see `MAX_EXTRA_DIR_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If the max path length is <= 0 it is an error (and a bug).
+ * If the max depth is <= 0 it is an error (and a bug).
+ * If the max filename length is <= 0 it is an error (and a bug).
+ * If a path is NULL it is an error.
+ * If a path is an empty string it is an error.
+ * If the path length (i.e. `strlen(path)` where path starts after the
+ initial `./` of the path in the `topdir`) is too long it is an error (see `MAX_PATH_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename (last component of the path) is too long it is an error (see `MAX_FILENAME_LEN` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * If a filename or directory name is not a sane relative path, not allowed
+ or will not be added for some other reason, it will be added to a relevant list to show to
+ the user later, to let them know it will not be added to the submission. By `relative` we mean it
+ must not start with `/` (which shouldn't happen even if you give an absolute
+ path) and by `sane` we mean that each component must match the regexp: `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$`.
+ * If a directory is unreadable it is an error.
+ * If a directory causes a cycle in the tree it is an error.
+ * If `stat(2)` on the path fails it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` is/are not found it is an error.
+ * If too many files that are not `prog.c`, `Makefile`, `remarks.md`,
+ `try.sh`, `prog.alt.c` or `try.alt.sh` are found, it is an error (see
+ `MAX_EXTRA_FILE_COUNT` in
+ [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
+ * Symlinks are not allowed but it is not an error (they will be added to a
+ list and ignored).
+ * If any file type other than a regular file, a directory or a symlink is
+ encountered it is an error.
+ * If there is an unknown error it is an error :-)
+5. Show each list to the user, asking if this is okay. The lists include:
+ * Ignored directories (those like `.git`, `CVS`, `RCCS` and `.svn`).
+ * Unsafe directory names that will not be added (i.e. those that are not
+ POSIX plus + safe chars only; see above step (4)). This includes directories
+ starting with a `.`.
+ * Forbidden files such as `index.html`, `README.md`, `prog`, `prog.alt`.
+ * Unsafe filenames that will not be added (i.e. those that are not POSIX
+ plus + safe chars only; see above step (4)). This includes files starting
+ with `.`.
+ * Symlinks found (these are not allowed).
+ * Directories to be made.
+ * Required files (`prog.c`, `Makefile` and `remarks.md`) to be copied.
+ * Non-required files to be copied.
+ * The user is asked to verify each list, including the lists of directories
+ and files to be made/copied, and if the user says it is not OK the program will abort.
+6. Make any directories if necessary (under
+`workdir/submit.USERNAME-SLOT.TIMESTAMP` i.e. the submission directory).
+ * Directories **MUST** be and are made with mode `0755`.
+ * If any directory is not this mode `txzchk(1)` will flag it.
+7. The non-ignored files are copied to their respective directories under the
+submission directory.
+ * `try.sh` and `try.alt.sh` **MUST** be and are copied as mode `0555`.
+ * All other files **MUST** be and are copied as mode `0444`.
+ * Anything else will be flagged by `txzchk(1)`.
+8. `cd submit.USERNAME-SLOT.TIMESTAMP` (i.e. switch to submission directory).
+9. `make -f Makefile clobber`.
+ * If this fails it is not an error but you are warned about it (it is an error only if the `Makefile`
+ does not exist); even so, see [Rule 20](next/rules.html#rule20).
+10. Traverse the new tree from `.` with additional steps from (4).
+ * If any file has an ignored directory name in it, it is an error.
+ * If a symlink is found it is an error.
+ * If any file type other than a directory or regular file exists it is an
+ error.
+ * If a forbidden filename exists it is an error.
+ * If any file or directory starts with `/` or is not POSIX plus + safe chars
+ only (see (4) above) it is an error.
+ * If the depth is too deep it is an error.
+ * If `prog.c`, `Makefile` or `remarks.md` are missing (or not readable
+ regular files) it is an error.
+ * `iocccsize(1)` (via the `mkiocccentry(1)` function `check_prog_c()`) will
+ be run on your `prog.c`, allowing you to override any warnings; if you do not
+ override an issue flagged it is an error but if warnings from `check_prog_c()`
+ are ignored you risk violating the [Rules](next/rules.html), including [Rule
+ 2](next/rules.html#rule2).
+ * `check_Makefile()` will be run on `Makefile`; if it is a non-readable or
+ empty file it is an error but otherwise you may override any warnings
+ (risking violating the [Rules](next/rules.html), especially [Rule
+ 17](next/rules.html#rule17) and [Rule 20](next/rules.html#rule20)).
+ * `check_remarks_md()` will be run on your `remarks.m`; if it is not a
+ regular readable file or it is empty it is an error. Otherwise it will
+ proceed. Note it does not check that there is any text in the file, just
+ that the file size is not 0, and having a `remarks.md` that is not size 0
+ but has no content is violating [Rule 17](next/rules.html#rule17) and [Rule
+ 19](next/rules.html#rule19).
+ * If any other error condition from step (4) occurs it is also an error.
+11. Report on any directories that were made and files that were copied in (7)
+but are now gone: asking the user to verify.
+12. Present the list of non-dot files that remain and ask the user to confirm.
+13. Ask the user for a submission title.
+14. Ask the user for a one line abstract of the submission.
+15. Ask the user for the number of authors and for each author ask a variety of
+questions (see below for more information on what kind of questions).
+16. Show the output of `ls -lakR .`, asking the user to confirm that the listing
+is okay.
+17. Create `.info.json` and run `chkentry(1)` on it.
+ * If `chkentry(1)` fails to validate the file make sure that you have
+ obtained and compiled the latest version of all the tools and you either are
+ in the repo's directory, you pass the options to give the path to the tools
+ or you have installed the latest tools!
+18. Create `.auth.json` and run `chkentry(1)` on it.
+ * If `chkentry(1)` fails to validate the file make sure that you have
+ obtained and compiled the latest version of all the tools and you either are
+ in the repo's directory, you pass the options to give the path to the tools
+ or you have installed the latest tools!
+19. Create the tarball.
+20. Run `txzchk(1)` on the tarball.
+
+If any of the steps fail or if the user says something is not okay, it aborts.
+Some of the other checks that are made:
-- If the files do not exist, are not regular files or cannot be read.
- If `prog.c` violates [Rule 2](next/rules.html#rule2) (see
[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
-- If `prog.c` is empty.
-- If `prog.c` has any high bit char (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
-- If `prog.c` has any NUL char (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+- If `prog.c` is empty (see [Rule 1](next/rules.html#rule1) and the
+[Guidelines](next/guidelines.html)).
+- If `prog.c` has any NUL (`\0`) char (see
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` has any unknown or invalid trigraph (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers a word buffer overflow (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If `prog.c` triggers an `ungetc(3)` error (see
-[iocccsize.c](https://github.com/ioccc-src/mkiocccentry/blob/master/iocccsize.c)).
+[rule_count.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/rule_count.c)).
- If the first rule in the `Makefile` is not `all`.
- If the `Makefile` does not have a `clean` rule.
- If the `Makefile` does not have a `clobber` rule.
- If the `Makefile` does not have a `try` rule.
-- If the `remarks.md` is empty.
-Conditions that one must correct, and which `mkiocccentry(1)` will prompt until
+
+Conditions that one **MUST** correct, and which `mkiocccentry(1)` will prompt until
they are correct, are:
+- Your _contest ID_ is invalidly formed.
+- Your _submit slot_ is < 0 or > `MAX_SUBMIT_SLOT` (see
+[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ is not in the range of 1 through `MAX_TITLE_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Your _title_ does not match the regexp `^[0-9a-z][0-9a-z._+-]*$`.
@@ -1197,8 +1381,7 @@ they are correct, are:
- An author _name_ is not 1 through `MAX_NAME_LEN` chars (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- Duplicate author _name_.
-- _Country code_ is invalid (not ISO 3166-1 2 character
-codes).
+- _Country code_ is invalid (i.e. it is not a ISO 3166-1 2 character code).
- An _email_, if provided, is not in the format of `x@y` or
if `x` or `y` contain a `@`, are empty or if the total length is longer than
`MAX_EMAIL_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
@@ -1208,17 +1391,20 @@ or `https://` or is longer than `MAX_URL_LEN` chars (see
or does not have anything after the `http://` or `https://`.
- A _mastodon handle_, if provided, is not in the form of
`@user@site` (i.e. starts with an `@`, has text following it and then another
-`@` followed by more text and has no other `@`) or is longer than `MAX_MASTODON_LEN` (see
+`@` followed by more text and has no other `@`), or if it is longer than `MAX_MASTODON_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- A _GitHub account_, if provided, does not start with an `@`,
-has more than one `@` or is longer than `MAX_GITHUB_LEN` (see
+has more than one `@`, does not have any text after the `@` or is longer than `MAX_GITHUB_LEN` (see
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- An _affiliation_, if provided, is longer than
`MAX_AFFILIATION_LEN` (see [limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)).
- An _author handle_, if the default is not accepted, does
not match the regexp `^[0-9A-Za-z][0-9A-Za-z._+-]*$`.
- An _author handle_ is repeated.
-- The output of `ls` on the submission directory is incorrect.
+
+The program does confirm that the information for each author is correct,
+allowing you to correct the information without having to start the program
+over.
Although the `mkiocccentry(1)` tool will verify everything for you, you may wish
to validate different parts individually with the different tools. As the
@@ -1240,8 +1426,13 @@ for more details on the tools that `mkiocccentry` either executes directly or
indirectly as part of the packaging process, especially if you wish to run one
or more of these tools manually.
+See also the
+FAQ on "[how to test everything at once without having to answer
+questions](#mkiocccentry_test)".
+
See also the [Guidelines](next/guidelines.html) and the [Rules](next/rules.html)
-(and in particular [Rule 17](next/rules.html#rule17)).
+(especially [Rule 1](next/rules.html#rule1), [Rule 2](next/rules.html#rule2), [Rule
+17](next/rules.html#rule17), [Rule 19](next/rules.html#rule19) and [Rule 20](next/rules.html#rule20)).
Jump to: [top](#)
diff --git a/markdown.html b/markdown.html
index 6f2d54bb7..aa9b7bf05 100644
--- a/markdown.html
+++ b/markdown.html
@@ -431,13 +431,13 @@
IOCCC Markdown guidelines version
-These IOCCC markdown guidelines are version 28.1 2024-12-27.
+These IOCCC markdown guidelines are version 28.1 2025-02-02.
IMPORTANT: Be sure to read the IOCCC rules and IOCCC
guidelines.
Jump to: top
-
-
IOCCC Markdown guidelines
+
+
IOCCC Markdown Guidelines Introduction
The IOCCC makes extensive use of markdown.
For example, when submitting to the IOCCC
@@ -454,9 +454,29 @@ FAQ on “remarks.md submission file”.
Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.
-
In particular there are things we ask people to please NOT use in
-markdown files for the IOCCC:
Jump to: top
+
+
+
+
IF (it is not required) you do use sections in your remarks.md file (this does
+not apply to other markdown files), PLEASE start at level three:
+
# Foo <=== no thank you
+ ## Foo <=== no thank you
+
Instead, start sections with 3 #s:
+
### Section 0
+
For each subsection of the current section, add another #, up to 6, going back
+to 3 for new sections. For instance:
+
### Section 0
+ ...
+ #### First subsection of section 0
+ ...
+ ##### Second subsection of section 0
+ ...
+ ###### Third subsection of section 0
+ ...
+ ### Section 1
+ ...
+ Etc.
Please do NOT use the name attributes in HTML <a>...</a> hyperlink elements
diff --git a/markdown.md b/markdown.md
index 480e52738..b823d434e 100644
--- a/markdown.md
+++ b/markdown.md
@@ -7,7 +7,7 @@
-These [IOCCC markdown guidelines](markdown.html) are version **28.1 2024-12-27**.
+These [IOCCC markdown guidelines](markdown.html) are version **28.1 2025-02-02**.
**IMPORTANT**: Be sure to read the [IOCCC rules](next/rules.html) and [IOCCC
@@ -16,8 +16,8 @@ guidelines](next/guidelines.html).
Jump to: [top](#)
-
-## IOCCC Markdown guidelines
+
+## IOCCC Markdown Guidelines Introduction
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
@@ -38,11 +38,46 @@ Nevertheless, the IOCCC does have certain practices that we ask authors to follo
Some of these relate to use of markdown directly and others relate to injecting HTML
into the markdown file.
-In particular there are things we ask people to please **NOT** use in
-markdown files for the IOCCC:
-
Jump to: [top](#)
+
+## Please DO start `remarks.md` sections at level 3 (`###`), increasing for subsections up to 6 (`######`)
+
+
+IF (it is not required) you do use sections in your `remarks.md` file (this does
+not apply to other markdown files), **PLEASE** start at level three:
+
+```
+ # Foo <=== no thank you
+ ## Foo <=== no thank you
+```
+
+Instead, start sections with 3 `#`s:
+
+
+```
+ ### Section 0
+```
+
+For each subsection of the current section, add another `#`, up to 6, going back
+to 3 for new sections. For instance:
+
+
+```
+ ### Section 0
+ ...
+ #### First subsection of section 0
+ ...
+ ##### Second subsection of section 0
+ ...
+ ###### Third subsection of section 0
+ ...
+ ### Section 1
+ ...
+ Etc.
+```
+
+
## Please do NOT use the `name` attributes in HTML `
...` hyperlink elements
diff --git a/next/Makefile.example b/next/Makefile.example
index 4e5438327..3380c00f8 100644
--- a/next/Makefile.example
+++ b/next/Makefile.example
@@ -153,12 +153,16 @@ ALT_TARGET=
#
DATA=
-
#################
# build the entry
#################
all: data ${TARGET}
+ # NOTE: only try.sh and try.alt.sh scripts will be made executable in
+ # the tarball so if you need any scripts that are executable, make sure
+ # to use ${CHMOD} +x on them like:
+ #
+ # ${CHMOD} +x foo.sh
.PHONY: all data try clean clobber install
diff --git a/next/guidelines.html b/next/guidelines.html
index 0903d2bde..cefbde128 100644
--- a/next/guidelines.html
+++ b/next/guidelines.html
@@ -461,7 +461,7 @@ writing by
contacting the judges.
-These IOCCC guidelines are version 28.35 2025-01-30.
+These IOCCC guidelines are version 28.36 2025-02-03.
The markdown form of these guidelines
@@ -609,12 +609,28 @@ that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in normal mode.
+IMPORTANT NOTE: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools then you will have to specify the options for the tools that
+are required like chkentry(1), txzchk(1) and fnamchk(1). But even if you
+have installed them but some tools are out of date (in the install path) it will
+cause problems. Additionally, if you do not have the most recent version when
+submitting a tarball it will be rejected for not having the right versions of
+the tools. This is why you MUST make sure you have the most recent
+version of all the tools and you either run it from the repo directory itself OR
+you install them (make install as via sudo or as root).
+
+
Rule 17 has been significantly modified
to account for the new mkiocccentry repo tools.
Thus, you are STRONGLY advised to use the mkiocccentry(1) tool
as found in the mkiocccentry repo
-to form the file to upload to the submit server. Not
-doing so puts you at a very big risk of violating Rule 17.
+using mkiocccentry(1) the submit server. Uploading
+a tarball not formed by mkiocccentry(1) puts you at a very big risk of
+violating Rule 17, especially as mkiocccentry(1) does a
+great number of things that are required, and it also runs many checks, and if
+any of those checks fail, you are at a very great risk of having your submission
+rejected for violating Rule 17.
See the
@@ -816,66 +832,6 @@ specific terminal brand. Programs that work in a standard xterm
are considered more portable.
Jump to: top
-
-
-The maximum total number of files that may be submitted has changed to 39 files.
-However, of those files, 5 are mandatory (prog.c, Makefile, remarks.md and
-the two JSON files generated by mkiocccentry(1), .info.json and
-.auth.json).
-
-
-Additionally, three of the files, if included, MUST be
-specific file(name)s and in the top level directory, or they will be counted as
-an extra file, not an optional file.
-
-
-In particular, any file that is not prog.c, Makefile, remarks.md,
-try.sh, prog.alt.c or try.alt.sh will be counted as an extra file, and if
-try.sh, prog.alt.c or try.alt.sh are not in the top level directory they
-will also be counted as an extra file. The .info.json and .auth.json files
-are not counted as extra files but are required.
-
-
-In other words, the actual amount of EXTRA files is 31.
-
-
-Of course, if you use the optional filenames without
-the files being our intended use, in order to get past the file limit, that
-would be an abuse of rules. For more details on the optional files, see the
-FAQ on the “try.sh script system”
-and the
-FAQ on “alt code”.
-
-
-If you do need to include more files, you may do so by including as an extra
-file, a tarball. This does NOT have to pass txzchk(1) tests; only the
-submission tarball must pass the txzchk(1) tests. See the txzchk
-section for more details on this important tool.
-
-
-If you DO include a tarball, and the build process or the program extracts
-said tarball(s), the make clobber rule MUST remove them.
-
-
-IMPORTANT REMINDER: make SURE your tarball does NOT reveal who you are!
-The mkiocccentry(1) tool creates a v7 format tarball to prevent this. You can
-do the same like:
-
-
tar --format=v7 -cJf foo.txz directory
-
-See Rule 17 and in particular the part about the maximum
-number of files. If you do not follow these points, you
-are at a great risk of violating Rule 17!
-
-
-NOTE: if you want to include a test-suite that requires a lot of files,
-please suggest this in your remarks.md and if your submission wins it can
-be done. In other words you should not use a tarball for a test-suite unless you
-have a very good reason for this (and if you do, make SURE you specify why
-in your remarks.md).
-
mkiocccentry
Rule 17 (the mkiocccentry(1) rule) states that
@@ -1082,6 +1038,66 @@ Of course, as txzchk does not extract the tarball, it is possible t
manually package your submission tarball, you could still be violating Rule
17.
+
+
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (prog.c, Makefile, remarks.md and
+the two JSON files generated by mkiocccentry(1), .info.json and
+.auth.json).
+
+
+Additionally, three of the files, if included, MUST be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+
+
+In particular, any file that is not prog.c, Makefile, remarks.md,
+try.sh, prog.alt.c or try.alt.sh will be counted as an extra file, and if
+try.sh, prog.alt.c or try.alt.sh are not in the top level directory they
+will also be counted as an extra file. The .info.json and .auth.json files
+are not counted as extra files but are required.
+
+
+In other words, the actual amount of EXTRA files is 31.
+
+
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules. For more details on the optional files, see the
+FAQ on the “try.sh script system”
+and the
+FAQ on “alt code”.
+
+
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does NOT have to pass txzchk(1) tests; only the
+submission tarball must pass the txzchk(1) tests. See the txzchk
+section for more details on this important tool.
+
+
+If you DO include a tarball, and the build process or the program extracts
+said tarball(s), the make clobber rule MUST remove them.
+
+
+IMPORTANT REMINDER: make SURE your tarball does NOT reveal who you are!
+The mkiocccentry(1) tool creates a v7 format tarball to prevent this. You can
+do the same like:
+
+
tar --format=v7 -cJf foo.txz directory
+
+See Rule 17 and in particular the part about the maximum
+number of files. If you do not follow these points, you
+are at a great risk of violating Rule 17!
+
+
+NOTE: if you want to include a test-suite that requires a lot of files,
+please suggest this in your remarks.md and if your submission wins it can
+be done. In other words you should not use a tarball for a test-suite unless you
+have a very good reason for this (and if you do, make SURE you specify why
+in your remarks.md).
+
See also the
FAQ on “txzchk”.
diff --git a/next/guidelines.md b/next/guidelines.md
index d8aa7f03c..709074189 100644
--- a/next/guidelines.md
+++ b/next/guidelines.md
@@ -49,7 +49,7 @@ Jump to: [top](#)
-These [IOCCC guidelines](guidelines.html) are version **28.35 2025-01-30**.
+These [IOCCC guidelines](guidelines.html) are version **28.36 2025-02-03**.
@@ -233,13 +233,30 @@ that if the directory exists already, you will have to remove it or move it
before this option will work a second time, just like in normal mode.
+
+**IMPORTANT NOTE**: if you run the program outside the repo directory
+(specifying the absolute or relative path to the tool) and you have not
+installed the tools then you will have to specify the options for the tools that
+are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
+have installed them but some tools are out of date (in the install path) it will
+cause problems. Additionally, if you do not have the most recent version when
+submitting a tarball it will be rejected for not having the right versions of
+the tools. This is why you **MUST** make sure you have the most recent
+version of all the tools and you either run it from the repo directory itself OR
+you install them (`make install` as via `sudo` or as root).
+
+
[Rule 17](rules.html#rule17) has been **significantly modified**
to account for the new [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) tools.
Thus, you are **STRONGLY** advised to use the `mkiocccentry(1)` tool
as found in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry)
-to form the file to upload to the [submit server](https://submit.ioccc.org). Not
-doing so puts you at a very big risk of violating [Rule 17](rules.html#rule17).
+using `mkiocccentry(1)` the [submit server](https://submit.ioccc.org). Uploading
+a tarball not formed by `mkiocccentry(1)` puts you at a very big risk of
+violating [Rule 17](rules.html#rule17), especially as `mkiocccentry(1)` does a
+great number of things that are required, and it also runs many checks, and if
+any of those checks fail, you are at a very great risk of having your submission
+rejected for violating [Rule 17](rules.html#rule17).
@@ -485,81 +502,6 @@ are considered more portable.
Jump to: [top](#)
-
-
-
-The maximum total number of files that may be submitted has changed to 39 files.
-However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
-the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
-`.auth.json`).
-
-
-
-Additionally, three of the files, if included, **MUST** be
-specific file(name)s and in the top level directory, or they will be counted as
-an extra file, not an optional file.
-
-
-
-In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
-`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
-`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
-will also be counted as an extra file. The `.info.json` and `.auth.json` files
-are not counted as extra files but are required.
-
-
-
-In other words, the actual amount of **EXTRA** files is 31.
-
-
-
-Of course, if you use the optional filenames without
-the files being our intended use, in order to get past the file limit, that
-would be an abuse of rules. For more details on the optional files, see the
-FAQ on the "[try.sh script system](../faq.html#try_script)"
-and the
-FAQ on "[alt code](../faq.html#alt_code)".
-
-
-
-If you do need to include more files, you may do so by including as an extra
-file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
-submission tarball must pass the `txzchk(1)` tests. See the [txzchk
-section](#txzchk) for more details on this important tool.
-
-
-
-If you **DO** include a tarball, and the build process or the program extracts
-said tarball(s), the make `clobber` rule **MUST** remove them.
-
-
-
-**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
-The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
-do the same like:
-
-
-```
- tar --format=v7 -cJf foo.txz directory
-```
-
-
-See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
-number of files](rules.html#max-files). If you do not follow these points, you
-are at a great risk of violating [Rule 17](rules.html#rule17)!
-
-
-
-**NOTE**: if you want to include a test-suite that requires a lot of files,
-please suggest this in your `remarks.md` and if your submission wins it can
-be done. In other words you should not use a tarball for a test-suite unless you
-have a very good reason for this (and if you do, make **SURE** you specify why
-in your `remarks.md`).
-
-
-
# `mkiocccentry`
@@ -818,6 +760,83 @@ manually package your submission tarball, you could still be violating [Rule
17](rules.html#rule17).
+
+
+
+The maximum total number of files that may be submitted has changed to 39 files.
+However, of those files, 5 are mandatory (`prog.c`, `Makefile`, `remarks.md` and
+the two JSON files generated by `mkiocccentry(1)`, `.info.json` and
+`.auth.json`).
+
+
+
+Additionally, three of the files, if included, **MUST** be
+specific file(name)s and in the top level directory, or they will be counted as
+an extra file, not an optional file.
+
+
+
+In particular, any file that is not `prog.c`, `Makefile`, `remarks.md`,
+`try.sh`, `prog.alt.c` or `try.alt.sh` will be counted as an extra file, and if
+`try.sh`, `prog.alt.c` or `try.alt.sh` are not in the top level directory they
+will also be counted as an extra file. The `.info.json` and `.auth.json` files
+are not counted as extra files but are required.
+
+
+
+In other words, the actual amount of **EXTRA** files is 31.
+
+
+
+Of course, if you use the optional filenames without
+the files being our intended use, in order to get past the file limit, that
+would be an abuse of rules. For more details on the optional files, see the
+FAQ on the "[try.sh script system](../faq.html#try_script)"
+and the
+FAQ on "[alt code](../faq.html#alt_code)".
+
+
+
+If you do need to include more files, you may do so by including as an extra
+file, a tarball. This does **NOT** have to pass `txzchk(1)` tests; only the
+submission tarball must pass the `txzchk(1)` tests. See the [txzchk
+section](#txzchk) for more details on this important tool.
+
+
+
+If you **DO** include a tarball, and the build process or the program extracts
+said tarball(s), the make `clobber` rule **MUST** remove them.
+
+
+
+**IMPORTANT REMINDER**: make **SURE** your tarball does **NOT** reveal who you are!
+The `mkiocccentry(1)` tool creates a v7 format tarball to prevent this. You can
+do the same like:
+
+
+```
+ tar --format=v7 -cJf foo.txz directory
+```
+
+
+See [Rule 17](rules.html#rule17) and in particular the part about the [maximum
+number of files](rules.html#max-files). If you do not follow these points, you
+are at a great risk of violating [Rule 17](rules.html#rule17)!
+
+
+
+**NOTE**: if you want to include a test-suite that requires a lot of files,
+please suggest this in your `remarks.md` and if your submission wins it can
+be done. In other words you should not use a tarball for a test-suite unless you
+have a very good reason for this (and if you do, make **SURE** you specify why
+in your `remarks.md`).
+
+
+
+
+
See also the
FAQ on "[txzchk](../faq.html#txzchk)".
diff --git a/next/remarks.example.md b/next/remarks.example.md
new file mode 100644
index 000000000..dbec0609b
--- /dev/null
+++ b/next/remarks.example.md
@@ -0,0 +1,27 @@
+# Instructions
+
+0. Create an empty file `remarks.md` in your submission directory
+(alternatively after reading this file, delete everything in it and rename it
+`remarks.md`).
+
+1. For help with markdown format please see this [helpful
+guide](https://www.markdownguide.org/basic-syntax/).
+
+2. Please see and follow the [IOCCC markdown
+guidelines](https://www.ioccc.org/markdown.html). Doing this helps the judges
+integrate your remarks into a `README.md`, should you win.
+
+3. After reading this file, write your remarks in your `remarks.md` file (as
+mentioned in step 0).
+
+4. When packaging your submission with `mkiocccentry(1)`, make sure that the
+`remarks.md` is in the `topdir`.
+
+**IMPORTANT NOTE**: make **SURE** you read the IOCCC
+[Rules](https://www.ioccc.org/next/rules.html) and
+[Guidelines](https://www.ioccc.org/next/guidelines.html)!
+
+# What should you say?
+
+Please see the
+FAQ on "[what to put in your remarks](../faq.html#remarks)".
diff --git a/next/rules.html b/next/rules.html
index dc636dd9a..eac4b8e46 100644
--- a/next/rules.html
+++ b/next/rules.html
@@ -460,9 +460,8 @@ writing by contacting the judges.
IOCCC Rules version
-
Jump to: top
-These IOCCC rules are version 28.19 2025-01-30.
+These IOCCC rules are version 28.23 2025-02-10.
The markdown form of these rules
@@ -973,8 +972,8 @@ if you need to include more files than this maximum.
Extra files are defined as files that are not the required files (prog.c,
Makefile, remarks.md and the two generated by mkiocccentry(1) .info.json
-and .auth.json) and the optional files (try.sh, prog.alt.c and
-try.alt.sh).
+and .auth.json) and files that are also not the optional files (try.sh,
+prog.alt.c and try.alt.sh).
Jump to: top
Rule 17 - The COMPLEX details
@@ -1044,7 +1043,9 @@ FAQ on “
Makefile compatibility”
for help.
-The remarks.md MUST be a non-empty file in markdown form. See also
+The remarks.md MUST be a non-empty file in markdown form
+(mkiocccentry(1) only checks the file size but if you do not have any text in
+it you still risk violating this rule). See also
Rule 18 and our
FAQ on “remarks.md”
and our
@@ -1056,7 +1057,7 @@ See also the markdown synta
and the CommonMark Spec.
-The xz compressed tarball file MUST be less than or equal 3999971 octets in size.
+The xz compressed tarball file MUST be less than or equal to 3999971 octets in size.
When your submission’s xz compressed tarball is uncompressed,
@@ -1092,11 +1093,10 @@ Filenames in your entry (that is, not including the files generated by the
-Be <= 38 characters in length
+Be <= 38 characters in length.
-NOT have a / (excluding the entry directory that
-the mkiocccentry(1) tool generates).
+NOT have a leading /.
NOT contain a path component of: . (that is, with
@@ -1116,12 +1116,12 @@ Match the regular expression
NOT be a directory depth > 4.
-NOT have a total path length > 99 characters.
+NOT have a total path length > 99 characters.
-Additionally, the submission tarball created by mkiocccentry(1) MUST have
-the following files (generated by the mkiocccentry(1) tool):
+The submission tarball created by mkiocccentry(1) MUST have
+the additional files that are generated by the mkiocccentry(1) tool:
+The chkentry(1) tool will validate these two JSON files prior to the tarball
+being formed.
+
+
+Files and directories in your submission tarball MUST be specific
+permissions and mkiocccentry(1) does this for you. In particular: directories
+MUST be drwxr-xr-x (i.e. 0755), the optional files, try.sh or
+try.alt.sh, if provided, MUST be -r-xr-xr-x (i.e. 0555) and all other
+files MUST be -r--r--r-- (i.e. 0444). If the files do not have these
+permissions, your submission WILL be rejected for violating Rule
+17! If you do need different permissions, then see the
+FAQ on “file permissions”. Also keep in mind
+Rule 4, Rule 5 and Rule 21.
+
+
The txzchk(1) tool will verify these (and other things) for you and
the chkentry(1) tool will do additional checks on the contents of the
.auth.json and .info.json files (including JSON validity). If these checks
-fail it is an error and mkiocccentry(1) will fail. In this case it is very
-possibly a bug; please report it as a bug at the mkiocccentry issues
+fail it is an error and mkiocccentry(1) will fail. In this case (it fails and
+you used mkiocccentry(1)) it is very possibly a bug; please report it as
+a bug at the mkiocccentry issues
page.
@@ -1162,7 +1178,8 @@ having your submission rejected for violating Rule 17!
The maximum number of files your submission tarball may contain, not counting
the optional files (prog.alt.c, try.sh, try.alt.sh) and the mandatory
-files (prog.c, Makefile, remarks.md) is 31. This is defined in the macro
+files (prog.c, Makefile, remarks.md plus the mkiocccentry(1) generated
+files .auth.json and .info.json) is 31. This is defined in the macro
MAX_EXTRA_FILE_COUNT in
soup/limit_ioccc.h
in the mkiocccentry repo. See the
@@ -1251,7 +1268,7 @@ do this AFTER the contest status h
CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
-
You (the author(s)) MUST own the contents of your submission OR
+
You (the author(s)) MUST own the content of your submission OR
you MUST HAVE PERMISSION from the owner(s) to submit their content.
You MUST NOT submit anything that cannot be submitted under that license.
Jump to: top
@@ -1278,7 +1295,7 @@ guidelines for additional markdown guidance.
make(1) compatibility the IOCCC
supports for more details.
-You are ENCOURAGED to use
+You are ENCOURAGED to use the
Makefile example, renamed as Makefile of course, for help in constructing your
Makefile. See the Makefile section in the
guidelines for more details.
diff --git a/next/rules.md b/next/rules.md
index 799cdb90b..8dfc688f8 100644
--- a/next/rules.md
+++ b/next/rules.md
@@ -51,11 +51,9 @@ Jump to: [top](#)
-These [IOCCC rules](rules.html) are version **28.19 2025-01-30**.
+These [IOCCC rules](rules.html) are version **28.23 2025-02-10**.
@@ -747,8 +745,8 @@ if you need to include more files than this maximum.
Extra files are defined as files that are not the required files (`prog.c`,
`Makefile`, `remarks.md` and the two generated by `mkiocccentry(1)` `.info.json`
-and `.auth.json`) and the optional files (`try.sh`, `prog.alt.c` and
-`try.alt.sh`).
+and `.auth.json`) and files that are also not the optional files (`try.sh`,
+`prog.alt.c` and `try.alt.sh`).
Jump to: [top](#)
@@ -821,7 +819,9 @@ for help.
-The `remarks.md` **MUST** be a **non**-empty file in markdown form. See also
+The `remarks.md` **MUST** be a **non**-empty file in markdown form
+(`mkiocccentry(1)` only checks the file size but if you do not have any text in
+it you still risk violating this rule). See also
[Rule 18](#rule18) and our
FAQ on "[remarks.md](../faq.html#remarks_md)"
and our
@@ -835,7 +835,7 @@ and the [CommonMark Spec](https://spec.commonmark.org/current/).
-The xz compressed tarball file **MUST** be less than or equal **3999971** octets in size.
+The xz compressed tarball file **MUST** be less than or equal to **3999971** octets in size.
@@ -850,8 +850,6 @@ Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` test. See
the [guidelines](guidelines.html) for more details on this tool.
-
-
**IMPORTANT**: Make **SURE** you have the most recent version of the
`mkiocccentry` toolkit! Not doing so will put you at a great risk of violating
@@ -861,7 +859,6 @@ for more details.
-
You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your
submission's xz compressed tarball. See the [guidelines](guidelines.html) for
@@ -880,9 +877,8 @@ Filenames in your entry (that is, not including the files generated by the
`mkiocccentry(1)` tool or the tools it or any other tool invokes) **MUST**:
-* Be <= **38** characters in length
-* **NOT** have a **`/`** (excluding the entry directory that
-the `mkiocccentry(1)` tool generates).
+* Be <= **38** characters in length.
+* **NOT** have a leading **`/`**.
* **NOT** contain a path component of: **`.`** (that is, with
the exception of files generated by `mkiocccentry(1)` itself, it must have
**NO** **`.`**).
@@ -892,11 +888,11 @@ the exception of files generated by `mkiocccentry(1)` itself, it must have
`^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$` (again, excluding files generated by
`mkiocccentry(1)`).
* **NOT** be a directory depth > 4.
-* **NOT** have a total path length > 99 characters.
+* **NOT** have a total **path** length > 99 characters.
-Additionally, the submission tarball created by `mkiocccentry(1)` **MUST** have
-the following files (generated by the `mkiocccentry(1)` tool):
+The submission tarball created by `mkiocccentry(1)` **MUST** have
+the additional files that are generated by the `mkiocccentry(1)` tool:
* `.auth.json` which contains information about the author or
@@ -904,12 +900,30 @@ authors (that will only be looked at if the submission wins).
* `.info.json` which contains information about the
entry.
+
+The `chkentry(1)` tool will validate these two JSON files _prior to_ the tarball
+being formed.
+
+
+
+Files and directories in your submission tarball **MUST** be specific
+permissions and `mkiocccentry(1)` does this for you. In particular: directories
+**MUST** be `drwxr-xr-x` (i.e. `0755`), the optional files, `try.sh` or
+`try.alt.sh`, if provided, **MUST** be `-r-xr-xr-x` (i.e. `0555`) and all other
+files **MUST** be `-r--r--r--` (i.e. `0444`). If the files do not have these
+permissions, your submission **WILL** be rejected for violating [Rule
+17](#rule17)! If you do need different permissions, then see the
+FAQ on "[file permissions](../faq.html#file_perms)". Also keep in mind
+[Rule 4](#rule4), [Rule 5](#rule5) and [Rule 21](#rule21).
+
+
The `txzchk(1)` tool will verify these (and other things) for you and
the `chkentry(1)` tool will do additional checks on the contents of the
`.auth.json` and `.info.json` files (including JSON validity). If these checks
-fail it is an error and `mkiocccentry(1)` will fail. In this case it is very
-**possibly** a bug; please [report it as a bug at the mkiocccentry issues
+fail it is an error and `mkiocccentry(1)` will fail. In this case (it fails and
+you used `mkiocccentry(1)`) it is very **possibly** a bug; please [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).
@@ -938,7 +952,8 @@ having your submission rejected for violating [Rule 17](#rule17)!
The maximum number of files your submission tarball may contain, not counting
the optional files (`prog.alt.c`, `try.sh`, `try.alt.sh`) and the mandatory
-files (`prog.c`, `Makefile`, `remarks.md`) is 31. This is defined in the macro
+files (`prog.c`, `Makefile`, `remarks.md` plus the `mkiocccentry(1)` generated
+files `.auth.json` and `.info.json`) is 31. This is defined in the macro
`MAX_EXTRA_FILE_COUNT` in
[soup/limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). See the
@@ -1049,7 +1064,7 @@ The entirety of your submission must be submitted under the following license:
**[CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/)**
-You (the author(s)) **MUST** own the contents of your submission **OR**
+You (the author(s)) **MUST** own the content of your submission **OR**
you **MUST HAVE PERMISSION** from the owner(s) to submit their content.
You **MUST NOT** submit anything that cannot be submitted under that license.
@@ -1090,7 +1105,7 @@ make(1) compatibility the IOCCC
supports](../faq.html#make_compatibility) for more details.
-You are **ENCOURAGED** to use
+You are **ENCOURAGED** to use the
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.
diff --git a/next/try.alt.sh b/next/try.alt.sh
old mode 100644
new mode 100755
diff --git a/next/try.sh b/next/try.sh
old mode 100644
new mode 100755
diff --git a/quick-start.html b/quick-start.html
index 77341230e..ff688bd6f 100644
--- a/quick-start.html
+++ b/quick-start.html
@@ -512,21 +512,25 @@ the
FAQ on”how to use mkiocccentry“)
and the mkiocccentry section in the
guidelines.
-
If you choose to risk violating rules, be sure and explain your reason
for doing so in your remarks.md file.