diff --git a/faq.html b/faq.html index bb3579d04..6af4dd737 100644 --- a/faq.html +++ b/faq.html @@ -684,24 +684,20 @@ explain how to use this tool. If you want to know what it is in simpler terms, see the FAQ on “what mkiocccentry is”.

As the Guidelines state, the synopsis is:

-
    mkiocccentry [options] work_dir prog.c \
-         Makefile remarks.md [file ...]
-

… where work_dir is a directory that will be used to build the submission -tarball, prog.c is your submission source code, Makefile is your submission’s -Makefile, remarks.md are your remarks (that will be the basis of the -README.md file which will be used to form the index.html file, if your -submission wins) and the remaining args are the paths to any other files you -wish to submit.

-

The work_dir MUST already exist, as a directory, and it is an error if it +

    mkiocccentry [options] workdir topdir
+

… where workdir is a directory that will be used to build the submission +tarball and topdir is the directory which has your files, including the +mandatory prog.c, Makefile and remarks.md.

+

The workdir MUST already exist, as a directory, and it is an error if it is not a directory that can be written to. In this directory your submission directory will be created, with the name based on your IOCCC registration 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.

-

If the subdirectory in the work directory already exists, you will have to +

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 -subdirectory), as it needs to be empty and the mkiocccentry(1) tool does not -check this for you as it could not do anything about anyway.

+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 diff --git a/faq.md b/faq.md index bc3d5046c..f12383137 100644 --- a/faq.md +++ b/faq.md @@ -300,28 +300,24 @@ FAQ on "[what mkiocccentry is](#about_mkiocccentry)". As the [Guidelines](next/guidelines.html) state, the synopsis is: ``` - mkiocccentry [options] work_dir prog.c \ - Makefile remarks.md [file ...] + mkiocccentry [options] workdir topdir ``` -... where `work_dir` is a directory that will be used to build the submission -tarball, `prog.c` is your submission source code, `Makefile` is your submission's -`Makefile`, `remarks.md` are your remarks (that will be the basis of the -`README.md` file which will be used to form the `index.html` file, if your -submission wins) and the remaining args are the paths to any other files you -wish to submit. +... where `workdir` is a directory that will be used to build the submission +tarball and `topdir` is the directory which has your files, including the +mandatory `prog.c`, `Makefile` and `remarks.md`. -The `work_dir` **MUST** already exist, as a directory, and it is an error if it +The `workdir` **MUST** already exist, as a directory, and it is an error if it is not a directory that can be written to. In **this** directory your **submission directory** will be created, with the name based on your IOCCC registration 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). -If the **_subdirectory_ in the _work directory_** already exists, you will have to +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 -subdirectory), as it needs to be empty and the `mkiocccentry(1)` tool does not -check this for you as it could not do anything about anyway. +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 diff --git a/next/guidelines.html b/next/guidelines.html index c03bbecb8..0903d2bde 100644 --- a/next/guidelines.html +++ b/next/guidelines.html @@ -461,7 +461,7 @@ writing by contacting the judges.

-These IOCCC guidelines are version 28.34 2025-01-24. +These IOCCC guidelines are version 28.35 2025-01-30.

The markdown form of these guidelines @@ -600,9 +600,11 @@ without having to put in answers each time, you can use the -d or < option to mkiocccentry for the tool to pseudo-randomly create answers for you. The -d option is an alias for -s 21701. An example use:

-
    mkiocccentry -d test_work prog.c Makefile remarks.md
+
    mkiocccentry -d workdir topdir

-where test_work is the directory which the tarball will be formed. Be aware +where workdir is the directory which the tarball will be formed and the +topdir is the directory which has the required files (prog.c, Makefile and +remarks.md) along with extra data files you wish to submit. Be aware 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.

@@ -821,20 +823,32 @@ are considered more portable. 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 in the limit MUST be -specific file(name)s: the OPTIONAL submission files, which are prog.alt.c, -try.sh and try.alt.sh, or else they WILL count as an extra file. Of -course, if you use the optional filenames without the files being their -intended, 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”. +.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 @@ -845,6 +859,12 @@ If you DO include a tarball, and the build process or the progr 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! @@ -911,8 +931,7 @@ correct details as you go along.

The synopsis of the mkiocccentry(1) tool is:

-
    mkiocccentry [options] work_dir prog.c \
-         Makefile remarks.md [file ...]
+
    mkiocccentry [options] workdir topdir

To help you with editing a submission, the mkiocccentry(1) tool has some options to write OR read from an answers file so you do not have to input diff --git a/next/guidelines.md b/next/guidelines.md index 9bfa3a3f0..d8aa7f03c 100644 --- a/next/guidelines.md +++ b/next/guidelines.md @@ -222,11 +222,13 @@ The `-d` option is an alias for `-s 21701`. An example use:

``` - mkiocccentry -d test_work prog.c Makefile remarks.md + mkiocccentry -d workdir topdir ```

-where `test_work` is the directory which the tarball will be formed. Be aware +where `workdir` is the directory which the tarball will be formed and the +`topdir` is the directory which has the required files (`prog.c`, `Makefile` and +`remarks.md`) along with extra data files you wish to submit. Be aware 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.

@@ -491,21 +493,36 @@ 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 in the limit **MUST** be -specific file(name)s: the **OPTIONAL** submission files, which are `prog.alt.c`, -`try.sh` and `try.alt.sh`, or else they **WILL** count as an extra file. Of -course, if you use the optional filenames without the files being their -intended, 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)". +`.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 @@ -518,6 +535,16 @@ 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 @@ -604,8 +631,7 @@ The synopsis of the `mkiocccentry(1)` tool is:

``` - mkiocccentry [options] work_dir prog.c \ - Makefile remarks.md [file ...] + mkiocccentry [options] workdir topdir ```

diff --git a/next/rules.html b/next/rules.html index 33f335b03..dc636dd9a 100644 --- a/next/rules.html +++ b/next/rules.html @@ -462,7 +462,7 @@ writing by contacting the judges.

Jump to: top

-These IOCCC rules are version 28.18 2025-01-24. +These IOCCC rules are version 28.19 2025-01-30.

The markdown form of these rules @@ -1034,22 +1034,6 @@ issues page.

-You submission may have additional files, however the filenames of those additional files MUST: -

- -

-The mkiocccentry(1) tool will not package any files that do not meet -those requirements. -

-

The Makefile MUST be a non-empty file in GNU Makefile form. See the Makefile section in the guidelines, @@ -1098,9 +1082,9 @@ more details on this tool and the -Your entry may NOT have subdirectories. However, you can provide files that -are in different directories as mkiocccentry(1) will copy them to the work -directory (see the guidelines for more details). +Your entry may have subdirectories, depending on the depth and total length of +the filenames. Certain directories like .git, RCCS, CVS and .svn are +skipped. For more information, see the guidelines.

Filenames in your entry (that is, not including the files generated by the @@ -1108,7 +1092,7 @@ Filenames in your entry (that is, not including the files generated by the

-Additionally, the tarball MUST have the following files (generated -by the mkiocccentry(1) tool): +Additionally, the submission tarball created by mkiocccentry(1) MUST have +the following files (generated by the mkiocccentry(1) tool):