From 0ba38856aa061837572436119dafe2b0d65df879 Mon Sep 17 00:00:00 2001 From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com> Date: Sat, 29 Nov 2025 09:30:38 -0800 Subject: [PATCH] Rebuild faq.html --- faq.html | 96 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/faq.html b/faq.html index 44dff4a67..1f9fc8ef2 100644 --- a/faq.html +++ b/faq.html @@ -453,7 +453,7 @@

IOCCC FAQ Table of Contents

-

This is FAQ version 29.01 2025-11-28.

+

This is FAQ version 29.02 2025-11-29.

0. Entering the IOCCC: the bare minimum you need to know

Jump to: top

@@ -982,7 +982,7 @@ for more details.

See the FAQ on “Rule 17” and -Rule 17 - Packaging +Rule 17 - Use mkiocccentry itself.

Do remember that if your submission requires different filenames, then you MUST make a COPY of them in your Makefile. See also @@ -1130,12 +1130,12 @@ level directory.

itself is an extra file, meaning it counts AS an extra file. This file does NOT need to pass the txzchk(1) tests; only your submission tarball needs to pass these tests. However see below if you do do this.

-

Please pay careful attention to Rule 17 - Packaging and in +

Please pay careful attention to Rule 17 - Use mkiocccentry and in particular the part about the maximum number of files per submission, which not only discusses the maximum number of files but also specific rules you must follow if you do include a tarball. Not following these points puts you at great risk -of violating Rule 17 - Packaging!

+of violating Rule 17 - Use mkiocccentry!

Also, remember what the guidelines say:

IMPORTANT REMINDER: make SURE your tarball does NOT reveal who you are! @@ -1159,7 +1159,7 @@ ultimate author of the code you submit.

you used as well as how you used them to help write your submission.

Jump to: top

-

Q 1.7: What are details behind Rule 17 - Packaging?

+

Q 1.7: What are details behind Rule 17 - Use mkiocccentry?

TL;DR Rule 17 - Use mkiocccentry(1)

This is a COMPLEX rule. Violating this rule WILL CAUSE YOUR SUBMISSION TO @@ -1178,7 +1178,7 @@ contains IMPORTANT tools and libraries such as:

  • chksubmit(1) (which uses jparse(3) and is a wrapper to chkentry(1))
  • The above mentioned tools will help you verify that your submission -conforms to Rule 17 - Packaging. Each of these tool has a -h +conforms to Rule 17 - Use mkiocccentry. Each of these tool has a -h option that provides command line help. For additional details of each tool, see its man page, and in some cases, the IOCCC guidelines.

    The maximum number of extra files is 31. See the @@ -1228,7 +1228,7 @@ for help.

    The remarks.md MUST be a non-empty file in markdown format (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 17 - Packaging +Rule 17 - Use mkiocccentry and our FAQ on “remarks.md”, our @@ -1322,7 +1322,7 @@ permissions and mkiocccentry(1) does this for you. In particular: d -r-xr-xr-x (i.e. 0555); and all other files MUST be -r--r--r-- (i.e. 0444). If any file or directory does not have the correct permissions, your submission WILL be rejected for violating -Rule 17 - Packaging!

    +Rule 17 - Use mkiocccentry!

    After mkiocccentry(1) creates the directories and copies the files with these modes, it also verifies them after the fact and if they are not correct it is an error.

    @@ -1346,7 +1346,7 @@ there should be no problem but if you were to package things manually it is possible there could be a problem and this poses a big risk of violating Rule 4 - Files or -Rule 17 - Packaging.

    +Rule 17 - Use mkiocccentry.

    The fnamchk(1), which txzchk(1) executes, will verify that the filename is correct. But if you do package your tarball manually, and you have a mismatch in what is in the tarball and the name, txzchk(1) will flag the @@ -1355,7 +1355,7 @@ discrepancy as an error and exit with non-zero.

    having your submission rejected for violating Rule 4 - Files or -Rule 17 - Packaging.

    +Rule 17 - Use mkiocccentry.

    Maximum number of files per submission

    @@ -1387,7 +1387,7 @@ The mkiocccentry(1) tool uses the v7 format. For instance you might

    IMPORTANT: where Rule 4 - Files, and -Rule 17 - Packaging. +Rule 17 - Use mkiocccentry. and the tools from the latest release of the mkiocccentry repo conflict, the IOCCC judges will use their best judgment which @@ -1424,7 +1424,7 @@ FAQ on “mkiocccentry repo bugs”.

    At the risk of stating the obvious: submissions that violate Rule 4 - Files, or -Rule 17 - Packaging +Rule 17 - Use mkiocccentry WILL BE REJECTED, so BE SURE to use the latest release of the mkiocccentry repo, to form and test your submission’s xz compressed tarball. Do NOT assume you have the most @@ -1669,7 +1669,7 @@ somehow, txzchk(1) will flag it as an error. When the judges run WILL BE REJECTED for violating -Rule 17 - Packaging!

    +Rule 17 - Use mkiocccentry!

    You may use whatever tools you need to develop your submission, including the use of git(1) or gh(1), just be sure that your submission code and your submission Makefile don’t depend on such tools.

    @@ -2122,7 +2122,7 @@ the judges ONLY; use of this option to validate your submission a great risk of violating Rule 4 - Files, or -Rule 17 - Packaging!).

    +Rule 17 - Use mkiocccentry!).

    As an example, if your submission directory is 00000000-0000-4000-0000-000000000000-3/ then you should run the following command:

    @@ -2144,7 +2144,7 @@ FAQ on “.info.json” as well as Rule 4 - Files, and -Rule 17 - Packaging +Rule 17 - Use mkiocccentry for more information.

    NOTE: the chksubmit(1) tool invokes chkentry(1) but as a contestant you do not need to worry about those details. One should use chksubmit(1) instead @@ -2235,12 +2235,12 @@ to be valid. If this is not the case your submission WILL BE re

  • The IOCCC contestant ID used as a username in the form of in the form of a UUID and submission number; see the Rules for more details on this, and in particular -Rule 17 - Packaging.
  • +Rule 17 - Use mkiocccentry.

    NOTE: if the contest ID is NOT in this format then fnamchk will report it as an error and your submission WILL BE rejected for violating -Rule 17 - Packaging.

    +Rule 17 - Use mkiocccentry.

  • tarball (double quoted string)

    • The xz compressed tarball filename.
    • @@ -2248,10 +2248,10 @@ violating

      IMPORTANT: this MUST match the actual tarball’s filename in order for this to be valid. If there is a mismatch you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging! +Rule 17 - Use mkiocccentry! Moreover, it is possible that txzchk will report a problem through fnamchk(1) which also puts you at great risk of violating -Rule 17 - Packaging. The +Rule 17 - Use mkiocccentry. The txzchk(1) tool will use the output of fnamchk to obtain the correct directory name in the tarball; if fnamchk fails to validate your filename, or if you have the wrong directory name in the @@ -2266,7 +2266,7 @@ tarball, this will be flaggd.

      in the mkiocccentry repo). If this is not the case you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging.

      +Rule 17 - Use mkiocccentry.

    • author_count (number)

      • How many authors this submission has.
      • @@ -2339,7 +2339,7 @@ the range of 1 THROUGH MAX_AFFILIATION_LEN (see in the mkiocccentry repo). If this is not the case you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging.

        +Rule 17 - Use mkiocccentry.

        NOTE: an affiliation does NOT have any affect on whether you will win or not.

      • past_winning_author (boolean)

          @@ -2426,7 +2426,7 @@ reported invalid by chksubmit(1), your submission will almost certa rejected for violating the Rules and in particular Rule 4 - Files, and -Rule 17 - Packaging.

          +Rule 17 - Use mkiocccentry.

          An obvious example where chksubmit(1) would fail to validate .auth.json is if there is a mismatch of type in the JSON file with what is expected, for instance, if in .auth.json the no_comment that we chose to not comment on is @@ -2437,7 +2437,7 @@ that must be established as valid by chksubmit(1)) your submission rejected for violating Rule 4 - Files, and -Rule 17 - Packaging +Rule 17 - Use mkiocccentry and in particular because chksubmit(1) would not validate the .auth.json file (and maybe other things too).

          @@ -2557,7 +2557,7 @@ this is not the case your submission WILL BE rejected!

        • The IOCCC contestant ID used as a username in the form of in the form of a UUID and submission number; see the rules for more details on this, and in particular -Rule 17 - Packaging.
        • +Rule 17 - Use mkiocccentry.
      • submit_slot (number)

          @@ -2569,7 +2569,7 @@ on this, and in particular in the mkiocccentry repo). If this is not the case you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging.

          +Rule 17 - Use mkiocccentry.

        • title (double quoted string)

          • A short name (length >= 1 THROUGH MAX_TITLE_LEN, defined in @@ -2579,7 +2579,7 @@ matches the regexp [a-z0-9][a-z0-9_+-]*.

          IMPORTANT: if this is NOT the case you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging!

        • +Rule 17 - Use mkiocccentry!

        • abstract (double quoted string)

          • A one line summary of your submission, with a length of 1 THROUGH @@ -2590,7 +2590,7 @@ in the mkiocccentry repoThe abstract may not contain a ; (semicolon), nor & (ampersand), nor , (comma).

            IMPORTANT: if your abstract is 0 in length or > the maximum abstract length you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          • tarball (double quoted string)

            • The xz compressed tarball filename.
            • @@ -2598,10 +2598,10 @@ stand a great risk of having your submission rejected for violating

              IMPORTANT: this MUST match the actual tarball’s filename in order for this to be valid. If there is a mismatch you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging! +Rule 17 - Use mkiocccentry! Moreover, it is possible that txzchk will report a problem through fnamchk(1) which also puts you at great risk of violating -Rule 17 - Packaging. +Rule 17 - Use mkiocccentry. The txzchk(1) tool will use the output of fnamchk to obtain the correct directory name in the tarball; if fnamchk fails to validate your filename, or if you have the wrong directory name in the @@ -2637,7 +2637,7 @@ violation, else false. calculated size is NOT violated but this is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging.

              +Rule 17 - Use mkiocccentry.

            • rule_2a_mismatch (boolean)

              • true if @@ -2656,7 +2656,7 @@ violation, else false.
              • calculated size is NOT violated but this is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging.

                +Rule 17 - Use mkiocccentry.

              • highbit_warning (boolean)

                • true if iocccsize detects a high bit (unescaped octets with the high @@ -2689,7 +2689,7 @@ else false.

                IMPORTANT: if the Makefile file has no problems and this is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

                +Rule 17 - Use mkiocccentry!

                See the FAQ on “Makefile” for more information.

              • @@ -2699,7 +2699,7 @@ for more information.

              IMPORTANT:: if the Makefile file does NOT have an all rule then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

              +Rule 17 - Use mkiocccentry!

              See the FAQ on “Makefile” for more information.

            • @@ -2710,7 +2710,7 @@ for more information.

              IMPORTANT: if the Makefile file does NOT have an all rule and this boolean is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

              +Rule 17 - Use mkiocccentry!

              See the FAQ on “Makefile” for more information.

              @@ -2721,7 +2721,7 @@ for more information.

              IMPORTANT: if the Makefile file does NOT have a clean rule and this boolean is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

              +Rule 17 - Use mkiocccentry!

              See the FAQ on “Makefile” for more information.

              @@ -2732,7 +2732,7 @@ for more information.

              IMPORTANT: if the Makefile file does NOT have an clobber rule and this boolean is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

              +Rule 17 - Use mkiocccentry!

              See the FAQ on “Makefile” for more information.

              @@ -2743,7 +2743,7 @@ for more information.

              IMPORTANT: if the Makefile file does NOT have a try rule and this boolean is true then you stand a good chance of having your submission rejected for violating -Rule 17 - Packaging!

              +Rule 17 - Use mkiocccentry!

              See the FAQ on “Makefile” for more information.

              @@ -2769,7 +2769,7 @@ for more information.

            IMPORTANT: if this is NOT the case you stand a great chance of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          • auth_JSON (double quoted string)

            • This MUST be ".auth.json", defined as AUTH_JSON_FILENAME in @@ -2782,7 +2782,7 @@ for more information.

            IMPORTANT: if this is NOT the case you stand a great chance of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          • c_src (double quoted string)

            • This MUST be "prog.c", defined as PROG_C_FILENAME in @@ -2792,7 +2792,7 @@ is your submission source code.

            IMPORTANT: if this is NOT the case you stand a great chance of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          • Makefile (double quoted string)

            • This MUST be "Makefile", defined as MAKEFILE_FILENAME in @@ -2805,7 +2805,7 @@ for more information.

            IMPORTANT: if this is NOT the case you stand a great chance of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          • remarks (double quoted string)

            • This MUST be "remarks.md", defined as REMARKS_FILENAME in @@ -2818,7 +2818,7 @@ for more information.

            IMPORTANT: if this is NOT the case you stand a great chance of having your submission rejected for violating -Rule 17 - Packaging!

          • +Rule 17 - Use mkiocccentry!

          The manifest array also OPTIONALLY has one or more of the field:

            @@ -2831,7 +2831,7 @@ and chksubmit will verify this for you; it is ALSO filenames are not unique, not POSIX plus + safe chars only, if they are the wrong permission and various other things. In these cases you stand a great risk of having your submission rejected for violating -Rule 17 - Packaging! +Rule 17 - Use mkiocccentry! On the other hand, ONLY mkiocccentry will verify that the files exist and can be read; txzchk(1) will NOT do this for you as it only LISTS the tarball: it does NOT extract it. @@ -2894,7 +2894,7 @@ out of range (see above for list). Two more examples would be if a field is missing or if an unknown filed is in the file. In these cases (and any others that must be established as valid by chksubmit) your submission would be rejected for violating -Rule 17 - Packaging, +Rule 17 - Use mkiocccentry, and in particular because chksubmit would not validate the .info.json file.

            If you wish to verify that your .info.json file is valid JSON then see the