# IOCCC FAQ Table of Contents This is FAQ version **29.06 2026-06-12**. ## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions) - **Q 0.0**: How can I enter the IOCCC? - **Q 0.1**: What is the `mkiocccentry` tool, how do I obtain it and how do I use it? - **Q 0.1.1**: What is `mkiocccentry(1)` in simple terms? - **Q 0.1.2**: How do I obtain the latest mkiocccentry toolkit? - **Q 0.1.3**: How do I compile the mkiocccentry toolkit? - **Q 0.1.4**: How do I install mkiocccentry(1) and related tools? - **Q 0.1.5**: How do I use mkiocccentry? - **Q 0.2**: What platform should I assume for my submission? - **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) - **Q 1.0**: How can I avoid re-entering the information to mkiocccentry? - **Q 1.1**: May I use a different source or compiled filename than prog.c or prog? - **Q 1.2**: What is markdown and how does the IOCCC use it? - **Q 1.3**: How do I report bugs in an `mkiocccentry` tool? - **Q 1.4**: How can I check if my submission passes tests without having to answer questions? - **Q 1.5**: What are extra files and how may I include additional files beyond the max allowed? - **Q 1.6**: May I use AI, LLM, Virtual coding assistants, or similar tools to write my submission? - **Q 1.7**: What are the details behind Rule 17 - use mkiocccentry? - **Q 1.8**: How can I avoid re-entering my UUID to mkiocccentry? - **Q 1.9**: How can I avoid having to move or delete my submission directory for the same workdir? - **Q 1.10**: Can I download my submission tarball from the submit server? - **Q 1.11**: Can I delete a submission from the submit server? - **Q 1.12**: What are the detailed recommendations for a submission Makefile? - **Q 1.13**: May I use GitHub or other services to develop my submission? ## 2. [IOCCC Judging process](#judging_process) - **Q 2.0**: What is the best way to ask a question about the IOCCC rules, guideline and tools? - **Q 2.1**: How can I comment or make a suggestion on IOCCC rules, guidelines and tools? - **Q 2.2**: Are there any compiler warnings that I should not worry about in my submissions? - **Q 2.3**: What types of entries have been frequently submitted to the IOCCC? - **Q 2.4**: How did an entry win the IOCCC that breaks Rule 2 - Size restrictions? - **Q 2.5**: How many submissions do the judges receive for a given IOCCC? - **Q 2.6**: How much time does it take to judge the contest? - **Q 2.7**: How many judging rounds do you have? - **Q 2.8**: Why do some IOCCC entries receive the Grand Prize or Best of Show award? - **Q 2.9**: How are winning IOCCC entries announced? - **Q 2.10**: Why don't you publish submissions that do not win? ## 3. [The mkiocccentry toolkit: finer details](#mkiocccentry_details) - **Q 3.0**: How can I validate my submission tarball? - **Q 3.1**: What is the `fnamchk` tool? - **Q 3.2**: How can I validate my submission directory? - **Q 3.3**: What is a `.auth.json` file? - **Q 3.4**: What is a `.info.json` file? - **Q 3.5**: What is an `author handle`? - **Q 3.6**: What is an `author_handle.json` file and how are they used? - **Q 3.7**: How can I find my author handle? - **Q 3.8**: What is an `entry_id`? - **Q 3.9**: What is a `.entry.json` file and how is it used? - **Q 3.10**: How can I validate any JSON document? ## 4. [Compiling IOCCC entries](#compiling) - **Q 4.0**: What Makefile rules are available to build or clean up IOCCC entries? - **Q 4.1**: What form of make(1) is supported by IOCCC? ## 5. [Dependencies for some IOCCC entries](#dependencies) - **Q 5.0**: How do I compile and run an IOCCC entry that requires X11? - **Q 5.1**: How do I compile and install SDL1 or SDL2 for entries that require it? - **Q 5.2**: How do I compile and install ncurses for entries that require it? - **Q 5.3**: How do I compile and run an IOCCC entry that requires sound? - **Q 5.4**: How do I compile and install tcpserver for entries that require it? - **Q 5.5**: How do I compile and install netpbm for entries that require it? - **Q 5.6**: How do I compile and install libjpeg-turbo for entries that require it? - **Q 5.7**: How do I compile and install ImageMagick for entries that require it? - **Q 5.8**: How do I compile and install OpenGL for entries that require it? - **Q 5.9**: How do I compile and install zlib for IOCCC entries that require it? - **Q 5.10**: How do I install Ruby for entries that require it? - **Q 5.11**: How do I install rake for entries that require it? - **Q 5.12**: How do I compile entries that use ncurses if we only have the old classic curses? ## 6. [Problems compiling IOCCC entries](#compile_problems) - **Q 6.0**: Why don't certain IOCCC entries compile and/or run? - **Q 6.1.1**: Why do some IOCCC entries fail to compile and/or run under macOS? - **Q 6.2**: Why do Makefiles use -Weverything with clang? ## 7. [Running IOCCC entries](#running_entries) - **Q 7.0**: What are `try.sh` and `try.alt.sh` scripts and why should I use them? - **Q 7.1**: An IOCCC entry messed up my terminal application, how do I fix this? - **Q 7.2**: Why does an IOCCC entry fail to compile and/or run? - **Q 7.2.1**: Why does an IOCCC entry fail to compile and/or run on my 64-bit system? - **Q 7.3**: How do I find out how to send interrupt/EOF etc. for entries that require it? - **Q 7.4**: How do I download individual winning entries or all winning entries of a given year? ## 8. [Changes made to IOCCC entries](#changes) - **Q 8.0**: What was changed in some IOCCC entries? - **Q 8.0.1**: How can I see the extended details of what was changed? - **Q 8.1**: Why were some calls to the libc function gets(3) changed to use fgets(3)? - **Q 8.2**: Why do some remarks seem inconsistent with the entry? - **Q 8.3**: What is the meaning of the file ending in .orig.c in IOCCC entries? - **Q 8.4**: What are alternate versions and why were they added to some entries? - **Q 8.5**: Why was arg count and/or type changed in main() in some older entries? - **Q 8.6**: Why were files added to, removed from or changed in some entries? - **Q 8.7**: What is the original source file? - **Q 8.8**: Why were some filenames changed? ## 9. [Helping the IOCCC](#help) - **Q 9.0**: How can I help the IOCCC? - **Q 9.1**: Is there a list of known bugs and (mis)features of IOCCC entries? - **Q 9.2**: How can I submit a fix to an IOCCC entry? - **Q 9.3**: How do I make a pull request to the GitHub repo? - **Q 9.4**: How can I report an IOCCC website problem? - **Q 9.5**: How can I submit a fix to the IOCCC website? - **Q 9.6**: How can I correct or update an IOCCC author's information? - **Q 9.7**: What should I do if I find a broken or wrong web link? - **Q 9.8**: How can I support the IOCCC? - **Q 9.9**: I deobfuscated some entry code, may I contribute the source? - **Q 9.10**: How do I report a bug in an IOCCC entry? ## 10. [Miscellaneous IOCCC](#misc) - **Q 10.0**: May I mirror the IOCCC website? - **Q 10.1**: May I use IOCCC content in an article, book, newsletter, or instructional material? - **Q 10.2**: Why do you sometimes use the first person plural? - **Q 10.3**: What is the purpose of the `.top`, `.allyear`, `.year` and `.path` files? - **Q 10.4**: What is the current meaning of the IOCCC terms Author, Entry, and Submission? - **Q 10.5**: Am I allowed to use IOCCC content? - **Q 10.6**: What is Mastodon and why does the IOCCC use it? - **Q 10.7**: How do I set certain tabstops for viewing source code in vi(m)? - **Q 10.8**: How do the menus on the website work and what can I do if they don't work? - **Q 10.9**: How do I find more information about a winning author of an entry? - **Q 10.10**: What is this cb tool that is mentioned in the IOCCC? - **Q 10.11**: What do the status.json JSON file indicate? - **Q 10.12**: What is the purpose of the `.date-range` files? - **Q 10.13**: What is a fun challenge? - **Q 10.14**: How do I submit a solution to a fun challenge? ## 11. [History of the IOCCC](#ioccc_history) - **Q 11.0**: How did the IOCCC get started? - **Q 11.1**: Why are some years missing IOCCC entries? - **Q 11.2**: What is the history of the IOCCC website? - **Q 11.3**: How has the Rule 2 size restrictions rule changed over the years? - **Q 11.4**: What is the **Great Fork Merge**? - **Q 11.5**: What is an IOCCC BOF? - **Q 11.6**: I do not understand the IOCCC, can you explain it to me? Jump to: [top](#) # The IOCCC FAQ
## Section 0: Entering the IOCCC: the bare minimum you need to know
Jump to: [top](#)
### Q 0.0: How can I enter the IOCCC?
To submit your code to the IOCCC, **follow the** [IOCCC Quick Start Guide](quick-start.html). Jump to: [top](#)
### Q 0.1: What is the `mkiocccentry` tool, how do I obtain it and how do I use it?
#### mkiocccentry repo
This toolkit is from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) and it is **required** that you use it to package your submission. Not doing so puts you at a great risk of violating the [Rules](next/rules.html) and in particular [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). Jump to: [top](#)
#### Q 0.1.1: What is `mkiocccentry` in simple terms?
The `mkiocccentry` tool first gathers your source 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 will give you a list of subdirectories, if any, that will be made, and files that will be copied to the submission directory. It will list files and directories that it will (for various reasons) not create as well, asking you to confirm these things are all okay. Some things are strictly forbidden (such as a directory tree too deep) and it will tell you about these as well, so you can fix it. Assuming you agree to the list of directories and files, it will make the directories (if necessary) and copy the files. It will then switch to the submission directory, run `make clobber` and then scan the directory again, looking for mismatches. If no errors are detected it will list everything to you again, asking you to confirm it is good. If everything is OK, it will write the required `.auth.json` and `.info.json` and then run `chksubmit(1)` on the directory. 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)" and the FAQ on "[chksubmit](#chksubmit)" for more information on these important tools, if you want more information. See the FAQ on "[how to upload you submission](#submit)" for details on how to register for the IOCCC, the FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)" for details on obtaining the latest release, the FAQ on "[compiling the mkiocccentry toolkit](#compiling_mkiocccentry)" for details on compiling and the FAQ on "[using mkiocccentry](#using_mkiocccentry)" for more details. Jump to: [top](#)
#### Q 0.1.2: How do I obtain the latest mkiocccentry toolkit?
Before you use it, make **SURE** you have the most recent version. If you do not have an mkiocccentry tool directory: ``` cd some_directory git clone git@github.com:ioccc-src/mkiocccentry.git cd mkiocccentry ``` If you already have an mkiocccentry tool directory: ``` cd mkiocccentry git fetch --all --tags git rebase ``` Jump to: [top](#)
#### Q 0.1.3: How do I compile the mkiocccentry toolkit?
Once you've obtained the **LATEST** version (see the FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)" to make sure of this), change to the `mkiocccentry` directory and then run: ``` make clobber all test ``` to compile all the tools and run the test-suite. You do not have to run the test-suite but if you wish to make sure all is in order you may. If you wish to skip that: ``` make clobber all ``` Jump to: [top](#)
### Q 0.1.4: How do I install mkiocccentry(1) and related tools?
After obtaining the toolkit (see the FAQ on "[obtaining the latest mkiocccentry toolkit](#obtaining_mkiocccentry)") and compiling the tools (see the FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)" above) run as either `sudo(8)` or root `make install`: ``` # if you use sudo(8): sudo make install # as root: make install ``` If everything goes well you should be able to run `mkiocccentry(1)`, `txzchk(1)`, `chksubmit(1)` and all the other installed tools from any directory, and the tools that rely on other tools will be able to find those required tools from any directory too. Some tools like `bug_report.sh` and `hostchk.sh` are not meant to be installed and will not work from any directory, however, nor should they be installed (some previously were but this was fixed post IOCCC28 and prior to IOCCC29). Jump to: [top](#)
#### Q 0.1.5: How do I use mkiocccentry?
Once you have registered, you will need to package your submission with the `mkiocccentry` tool. If you have not already obtained the toolkit, see the FAQ on "[obtaining the most recent mkiocccentry toolkit](#obtaining_mkiocccentry)", the FAQ on "[compiling mkiocccentry](#compiling_mkiocccentry)" and the FAQ on "[installing the mkiocccentry tools](#installing)" if you have not already done so. The below details discuss this very important tool. As it is complicated we will explain how to use this tool. If you want to know what it is in simpler terms, see the FAQ on "[what mkiocccentry is](#about_mkiocccentry)". As the [Guidelines](next/guidelines.html) state, the synopsis is: ``` 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 along with the timestamp; see the [rules](next/rules.html) for more details on this, and in particular [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). **IMPORTANT NOTE**: the tools that require other tools, `mkiocccentry(1)` and `txzchk(1)`, will, as of version `2.0.2 2025-03-11`, search under `$PATH`. If you have an earlier version and you have not installed the tools and run the tools from outside the repo directory, you will have to use the options to the tools to set the path to the required tools. 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. This _subdirectory is where your directories will be made and 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 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 mentioned above, and as described in the "[finer details](#mkiocccentry_details)" section. **PLEASE NOTE**: if your submission directory (or topdir) has certain errors the mkiocccentry tool will exit with a fatal error, asking you to fix the problem first. Jump to: [top](#)
### Q 0.2: What platform should I assume for my submission?
Your submission must be able be compiled with **clang** or **gcc** and run under at least one flavor of a UNIX system that conforms to the [SUS](https://en.wikipedia.org/wiki/Single_UNIX_Specification), otherwise known as the [The Single UNIX Specification Version 4](https://unix.org/version4/overview.html). or [later SUS](https://unix.org/online.html). [The Single UNIX Specification Version 4](https://unix.org/version4/overview.html) includes [X/Open Curses, Issue 7](https://pubs.opengroup.org/onlinepubs/9699909599/toc.pdf), so your submission is free to use "**curses**" (i.e., the `curses` library and the `curses.h` include file). Your entry is also free to use [ncurses](https://invisible-island.net/ncurses/announce.html) (i.e., the `ncurses` library and the `ncurses.h` include file). See also the FAQ on "[compile and install ncurses](#ncurses)". Jump to: [top](#)
### Q 0.3: What should I put in my submission Makefile?
We recommend starting with the sample (renamed as `Makefile` of course) as a starting point for your entry's `Makefile`: - [view example Makefile](%%REPO_URL%%/next/Makefile.example) - [Makefile.example](next/Makefile.example) The `Makefile` is a file used by the `make(1)` command that contains rules and UNIX shell-style commands. The first and default rule should be the `all` rule and should build your entry's executable file. There are other rules that should be present in your Makefile, and which mkiocccentry attempts to find; see below. If your entry depends on a particular source file name during compilation or execution, your `Makefile` should copy `prog.c` into the desired filename. See the FAQ on "[source and compiled filenames](#prog_c)" for an example. If you are not familiar `Makefile`s, you might consider the following tutorials: - [GNU make](https://www.gnu.org/software/make/manual/make.html#Introduction) - [What is a Makefile and how does it work?](https://opensource.com/article/18/8/what-how-makefile) - [Learn Makefiles](https://makefiletutorial.com) For the `make(1)` _connoisseur_: As of 2023, IOCCC judges use [GNU make compatible](https://www.gnu.org/software/make/) `make(1)` command that is compatible with GNU Make version 3.81. Your Makefile should be compatible with this; see the FAQ on "[Makefile compatibility](#gmake)" for more details and help. #### Expected `make` rules: The following rules should exist in your Makefile: - `all` * This rule should be the first rule and it should compile your submission. - `clean` * This rule should remove any intermediate build files, for example `.o` files or other intermediate build files. It should **NOT** remove compiled programs (see `clobber` below). - `clobber` * This rule should restore the original state of the submission's directory. It should depend on the `clean` rule and it should remove the compiled program(s), clean up any files made by the program etc. - `try` * run the program in a way you suggest. If you use the `try.sh` script system, which we do like, you can have this rule invoke the script (`./try.sh`). See the FAQ on the "[try.sh scripts system](#try_scripts)" for more details. Although the `mkiocccentry(1)` tool only checks for those rules, the most up to date `Makefile.example` does have other rules like `everything` and `alt`, and we encourage you to use the one linked to above. See also the FAQ on "[detailed Makefile recommendations](#makefile_details)" for more details. Jump to: [top](#)
### Q 0.4: What should I put in the remarks.md file of my submission?
**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.md) - [remarks.md template](next/remarks.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 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 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 (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). #### What does not help: - admitting that your entry is not very obfuscated (you see, the contest is called the **IOCCC**, not the **INVOCCC** :-) ); but even if you do not admit it, not very obfuscated entries have a minuscule chance to win (although [2000/tomx](2000/tomx/index.html) is a notable counterexample). - mentioning your name or any identifying information in the remark section (or 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 (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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)). Jump to: [top](#)
### 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 included in your submission), it can be helpful to include a `try.sh` script: - [view example try.sh](%%REPO_URL%%/next/try.sh) - [download example try.sh](next/try.sh) - [view example try.alt.sh](%%REPO_URL%%/next/try.alt.sh) - [download example try.alt.sh](next/try.alt.sh) The template `try.sh` script can be used as a starting point, or you can look at some of the others in past winning entries, to get some ideas. It is not detrimental to your chances of winning if you do not include one as not all submissions can make use of them. Nevertheless, it is helpful to include ways to use your program and as submitted Makefiles should have a `try` rule, if you have creative ways this can be a bonus. It does not mean that a program that cannot be used with other programs is less interesting or less likely to win, but we do enjoy interesting and creative uses of submissions. If you have alternate code that you are including, then you can use the `try.alt.sh` template as well. We recommend that you include the use of these scripts in the `try` rule in the example Makefile that you modify for your submission. See the FAQ on "[submission Makefiles](#makefile)". Jump to: [top](#)
### Q 0.6: What permissions may my files be and what if I need different permissions?
Files in your submission tarball **MUST** be specific permissions. In particular: directories **MUST** be `drwxr-xr-x` (i.e. `0755`), the optional files, files ending with `.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. See the FAQ on "[Rule 17](#rule17)" and [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry) itself. Do remember that if your submission requires different filenames, then you **MUST** make a **COPY** of them in your `Makefile`. See also [Rule 5 - Do NOT modify submitted files or filenames or parent directories](next/rules.html#rule5-modifying-files). Jump to: [top](#)
## Section 1: Entering the IOCCC: more help and details
Jump to: [top](#)
### Q 1.0: How can I avoid re-entering the information to mkiocccentry?
`mkiocccentry(1)` has some options to help write _OR_ read from an answers file so you do not have to input the author(s) or the submission details (like the abstract, summary etc.), just to change a file. To write to `answers.txt` try: ``` mkiocccentry -a answers.txt ... ``` Alternatively, if you wish to overwrite a file, you can use the `-A` flag with the same option argument. Be **very careful** that you do not accidentally overwrite your `prog.c` or some other important file! To make use of the answers file, use the `-i answers` option like: ``` mkiocccentry -i answers.txt ... ``` Jump to: [top](#)
### Q 1.1: May I use a different source or compiled filename than prog.c or prog?
While your submission's source filename, as submitted, must be `prog.c`, your entry's `Makefile` may copy `prog.c` to a different filename as part of the compiling/building process. For example: ``` # Makefile continues above ... all: desired_name desired_name: desired_name.c rm -f $@ cc desired_name.c -o $@ desired_name.c: prog.c rm -f $@ cp -f prog.c $@ clean: rm -f desired_name.o clobber: clean rm -f desired_name.c desired_name # Makefile continues below ... ``` We recommend that the `make clobber` rule remove files that your entry creates as part of the compiling/building process. You may also copy the compiled `prog` into a different file as part of compiling process. For example: ``` # Makefile continues above ... all: desired_name different_name: prog rm -f $@ cp -f prog $@ clean: rm -f prog.o clobber: clean rm -f desired_name # Makefile continues below ... ``` Jump to: [top](#)
### Q 1.2: What is markdown and how does the IOCCC use it?
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/). For example, when [submitting to the IOCCC](next/submit.html), we have people submit remarks about their submission(s) in markdown format. Every [winning IOCCC entry](years.html) uses a `README.md` markdown file as the basis for forming the `index.html` web page for that entry. All generated HTML pages on the [Official IOCCC website](index.html) start with some markdown content. **IMPORTANT**: Please read the [IOCCC markdown guidelines](markdown.html) as it lists things you **should NOT use** in markdown files and things you **should do** as well. See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide. See also [CommonMark Spec](https://spec.commonmark.org/current/). Jump to: [top](#)
### Q 1.3: How do I report bugs in an `mkiocccentry` tool?
As the [mkiocccentry toolkit](https://github.com/ioccc-src/mkiocccentry) is crucial in the contest, both for submitters and the judges, if you find a bug (or you think you find a bug) we would be grateful if you were to report it at the [mkiocccentry issues page](https://github.com/ioccc-src/mkiocccentry/issues). Please see the FAQ on "[reporting bugs and other issues in the mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#bugs)" in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) for more thorough details on bug reporting. Jump to: [top](#)
#### Q 1.4: How can I check if my submission passes tests without having to answer questions?
In case you do not have a UUID or you simply want to test if `mkiocccentry(1)` does not detect any issues with your submission, without having to answer all the questions, you can use the `-d` option (which is an alias for `-s 21701` where `21701` is the seed) to have the tool make up pseudo-randomly selected answers. Please note that the tool will **NOT** delete the directory it makes so if you do have to try again you'll have to remove it (you can have it delete it if you use the `-x` option though). An example use of this option is: ``` mkiocccentry -d workdir topdir ``` This will run the tests that `mkiocccentry(1)`, write the JSON files, use `chksubmit(1)`, package the tarball and run `txzchk(1)` on it. If you don't want to deal with the having to move or delete the submission directory, you could instead do: ``` mkiocccentry -x -d workdir topdir ``` See also the FAQ on "[mkiocccentry](#mkiocccentry)", the FAQ on "[using mkiocccentry](#using_mkiocccentry)", the FAQ on "[.info.json](#info_json)", the FAQ on "[.auth.json](#auth_json)", the FAQ on "[chksubmit](#chksubmit), the FAQ on "[txzchk](#txzchk)" and the FAQ on "[fnamchk](#fnamchk)" for more details.
### Q1.5: What are extra files and how may I include additional files beyond the max allowed?
Extra files are defined as files that are not the free files (the required files `prog.c`, `Makefile`, `remarks.md` and the optional `try.sh`, `try.alt.sh`, `prog.alt.c` and the two generated by `mkiocccentry(1)` `.info.json` and `.auth.json`). **NOTE**: optional filenames are only optional if they are in the submission top level directory. You may provide up to 31 extra files. If you need to include more files than this, you may include a tarball that 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 - Use mkiocccentry](next/rules.html#rule17-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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! Also, remember what the [guidelines](next/guidelines.html) say: > **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 this by creating the tarball like: ``` tar --format=v7 -cJf foo.txz directory ``` Jump to: [top](#)
### Q 1.6: May I use AI, LLM, Virtual coding assistants, or similar tools to write my submission?
You are free to use whatever tools you wish to write your code. This includes tools that are AI based, LLM (large language model), Virtual coding assistants, code generators, or similar tools, as well as your own tools. The [IOCCC judges](judges.html) do not discriminate on the basis of the tools used to write obfuscated C code so long as you are the ultimate author of the code you submit. If you do use such tools, **PLEASE mention** in your `remarks.md` which tools 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 - Use mkiocccentry?
### TL;DR Rule 17 - Use `mkiocccentry(1)` This is a **COMPLEX** rule. **Violating this rule WILL CAUSE YOUR SUBMISSION TO BE REJECTED!** To help you avoid such a rejection, you are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool, based on the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), to form your submission's xz compressed tarball. The [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) contains **IMPORTANT** tools and libraries such as: - `mkiocccentry(1)` - `iocccsize(1)` - `txzchk(1)` - `fnamchk(1)` - `jparse(3)` - `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 - Use mkiocccentry](next/rules.html#rule17-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](next/guidelines.html). The maximum number of **extra files** is 31. See the FAQ on "[extra files](#extra-files)" for more details. Below we will list more details and link to relevant FAQs as well. Jump to: [top](#) ### Rule 17 - The COMPLEX details Each submission **MUST** be in the form of an xz compressed tarball. The xz compressed tarball filename **MUST** be of the form: `^submit.username-slot_num.[1-9][0-9]{9,}.txz$`. ... where _`username`_ is your IOCCC registration username **in the form of a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)** (see [RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562) for details), and where _`slot_num`_ is a single decimal digit integer (i.e., >= `0` and <= `9`). In particular, `username` is in the form of: `xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx` where `'x'` is a hex digit in the range of `[0-9a-f]`, 4 is the UUID version, and `N` is one of `8`, `9`, `a`, or `b`. Your xz compressed tarball **MUST** contain, **at a minimum**, the following files, in the **TOP LEVEL** directory (see below for more details on each file in this list): - `prog.c`: your submission code. - `Makefile`: your Makefile that is based on [next/Makefile.example](next/Makefile.example). - `remarks.md`: your remarks about the submission in markdown format. - `.auth.json`: a JSON file about the author details (which will only be looked at by the judges IF it wins), generated by the `mkiocccentry(1)` tool. - `.info.json`: a JSON file about the submission itself which will be looked at by the judges during judging. Note that these do not count against extra files. Neither do the `try.sh`, `prog.alt.c` or `try.alt.sh`, should you provide them, and they are in the top level directory. See the FAQ on "[extra files](#extra-files)" for more details on what this means, should you need to include additional files. The `prog.c` is probably pretty obvious if you're here. :-) The `Makefile` **MUST** be a **non**-empty file in **[GNU Makefile](https://www.gnu.org/software/make/manual/make.html)** format. See the [Makefile section in the guidelines](next/guidelines.html#makefile), the FAQ on "[submission Makefiles](#submission_makefile)" and the FAQ on "[IOCCC make(1) compatibility](#make_compatibility)" 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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry) and our FAQ on "[remarks.md](#remarks_md)", our FAQ on "[markdown](#markdown)" and our [markdown guidelines](markdown.html). See also the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide and the [CommonMark Spec](https://spec.commonmark.org/current/). The `.auth.json` file is created by `mkiocccentry(1)` and it holds information about the author(s) of the submission. It will **ONLY** be looked at if your submission wins but it **MUST** still be valid according to `jparse(3)` **AND** `chksubmit(1)` even if it does not win; if `chksubmit(1)` does not validate this file your submission **WILL** be rejected for violating Rule 17! See the FAQ on "[.auth.json](#auth.json)" for more details on this file. The `.info.json` file is created by `mkiocccentry(1)` and it holds information about the submission itself. It also **MUST** be valid according to **BOTH** `jparse(3)` **AND** `chksubmit(1)`. See the FAQ on "[.info.json](#info.json)" for more details on this file. See the FAQ on "[chksubmit(1)](#chksubmit)" for more details on this important tool. The tool performs a lot of checks, both directly and indirectly, and if it or any other tool detects **ANY** problem, you are **HIGHLY** encouraged to fix it and try again. On the other hand, some issues are errors and you **MUST** fix those. If you do use `mkiocccentry(1)` (which we STRONGLY recommend you do) and you run into a problem, you might see the FAQ on "[how to ask a question about the IOCCC rules, guidelines and tools](#questions)". If you believe you have encountered a bug, feel free to open a bug report at the [mkiocccentry repo issues page](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E). The xz compressed tarball file **MUST** be <= **3999971** octets in size. When your submission's xz compressed tarball is uncompressed, the total size of your submission (the sum of the size of the program source code, remarks/comments, Makefile and all other files) **MUST** be <= **28314624** octets (**27651K**) in size. One of the many checks `txzchk(1)` performs is summing up the total size. Of course if you manipulate the tarball to get past this you risk violating this rule. Your submission's xz compressed tarball **MUST** pass the `txzchk(1)` tests. See the [guidelines on txzchk(1)](next/guidelines.html#txzchk) 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 this rule! See the FAQs on "[obtaining, compiling, installing and using the mkiocccentry toolkit](#mkiocccentry)" for more details. You are **HIGHLY ENCOURAGED** to use the `mkiocccentry(1)` tool to form your submission's xz compressed tarball. See the [guidelines on mkiocccentry(1)](next/guidelines.html#mkiocccentry) for more details on this tool and see the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) for the toolkit itself. Your entry **MAY** have subdirectories, depending on the depth (a max depth, noted below) and total length of the filenames. Certain directories like `.git`, `RCCS`, `CVS` and `.svn` (amongst others) are skipped. For more information, see the FAQ on "[subdirectories](#subdirectories)". With the exception of those generated by the `mkiocccentry(1)` tool or the tools it or any other tool invokes, files in your submission **MUST**: - 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** dot file including `.` itself). - **NOT** contain a path component of: **`..`** (that is, **NO** path component that matches the regular expression **`^..$`**). - Match the regular expression `^[0-9A-Za-z]+[0-9A-Za-z_+.-]*$` (again, excluding files generated by `mkiocccentry(1)`). - **NOT** have a directory/file depth > 4. - **NOT** have a total **path** length > 99 characters. Again, the submission tarball **MUST** have the mkiocccentry(1) created JSON files: - `.auth.json` which contains information about the author or authors (that will only be looked at if the submission wins). - `.info.json` which contains information about the submission. The `chksubmit(1)` tool will validate these two JSON files, and do other checks on your submission directory as well, _prior to_ `mkiocccentry(1)` forming the tarball. See the FAQ on "[chksubmit(1)](#chksubmit)" for more details on this tool. 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`); any file ending with `.sh` **MUST** be `-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 - Use mkiocccentry](next/rules.html#rule17)! 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**. If you do need different permissions, then see the FAQ on "[file permissions](#file_perms)". Also keep in mind [Rule 4 - Required files](next/rules.html#rule4-required-files), [Rule 5 - Do NOT modify submitted files or filenames or parent directories](next/rules.html#rule5-modifying-files), and [Rule 16 - Anonymous judging](next/rules.html#rule16-anonymous-judging). The `txzchk(1)` tool will also verify file/directory permissions (and many other things) for you, and so will `chksubmit(1)` (along with other checks on files and directories in your submission directory, including the two required JSON files, `.auth.json` and `.info.json`). If these checks fail it is an **error** and `mkiocccentry(1)` will abort. 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). The tarball filename **MUST** pass `fnamchk(1)`; the tool `txzchk(1)` will run `fnamchk(1)` as part of its algorithm. If you use `mkiocccentry(1)` 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 - Required files](next/rules.html#rule4-required-files) or [Rule 17 - Use mkiocccentry](next/rules.html#rule17). 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 discrepancy as an error and exit with non-zero. These checks **MUST PASS**. If they do not you stand a significant chance of having your submission rejected for violating [Rule 4 - Required files](next/rules.html#rule4-required-files) or [Rule 17 - Use mkiocccentry](next/rules.html#rule17).
#### Maximum number of files per submission
The maximum number of files your submission tarball may contain, not counting the free files (`prog.c`, `remarks.md`, `Makefile`, `prog.alt.c`, `try.sh`, `try.alt.sh`,, `.info.json` and `.auth.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 FAQ on "[what extra files are and how to include more](#extra-files)" if you need to include more files. If you do include a tarball that takes your extra files count over the maximum, you **MUST** explain this in your `remarks.md` file! **PLEASE** do not include a tarball with extra files for a test-suite; instead mention in your remarks that you have extra files for a test-suite that can be included should your submission win. Of course if you don't need that many files for a test-suite you are more than welcome to include those files in your submission. If you need to extract a tarball by some Makefile, or perhaps the program itself, then `make clobber` **MUST** remove everything that the extraction created! Tarballs **MUST** only create files and directories _under_ the submission directory. They may **NOT** contain absolute paths (paths that start with `/`)! `txzchk` does **NOT** check other tarballs so **YOU MUST** verify these details yourself. **IMPORTANT REMINDER**: **MAKE SURE** your tarball does not reveal who you are! The `mkiocccentry(1)` tool uses the v7 format. For instance you might try: ``` tar --format=v7 -cJf foo.txz directory ```
**IMPORTANT**: where [Rule 4 - Required files](next/rules.html#rule4-required-files), and [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry) and the tools from the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) conflict, the [IOCCC judges](judges.html) will use their best judgment which is likely to favor [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) code. This means you should **MAKE SURE** that you use `mkiocccentry(1)` to package your submission; `mkiocccentry(1)` will run the above mentioned tools (that do not act on the tarball) **before** creating the tarball and after the tarball is created it will then verify that the tarball is okay by running `txzchk(1)` on it. If any step fails it is an error and submitting the submission will result in violating this rule. **MAKE SURE** you use the correct release of the repository; you should do this **AFTER** the contest opens (pull any changes or if you prefer download the repository via the download option at GitHub). See the FAQ on "[obtaining the latest release of mkiocccentry](#obtaining_mkiocccentry)" for more help on ensuring you do have the most up to date release. We recommend that you run `make` and then install the tools (and man pages) via `make install` (as root or using `sudo(8)`) to help you run these tools from your submission's directory (or any other directory). The `make install` will install in `/usr/local`. However, **you do not have** to install them, but in that case you'll have to run it from the toolkit's directory or use the correct options to specify the path to the necessary tools, and also specify the path to your files, which can be problematic. These tools will link in the `jparse(3)` library, the `dbg` library and the `dyn_array` library as well as the `pr(3)` and `soup(3)` libraries; `chksubmit(1)` uses the JSON parser (`jparse(3)`) to validate and parse the [JSON](https://www.json.org/json-en.html) files but the other tools use parts of the `jparse` utility functions as well. If you run into a problem with one or more of these tools, **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), **making sure to run `bug_report.sh`**. See the [guidelines](next/guidelines.html) for help here and also read our FAQ on "[mkiocccentry repo bugs](#mkiocccentry_bugs)". At the risk of stating the obvious: submissions that violate [Rule 4 - Required files](next/rules.html#rule4-required-files), or [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry) **WILL BE REJECTED**, so **BE SURE** to use the latest release of the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), to form and test your submission's xz compressed tarball. Do **NOT** assume you have the most recent release without pulling or downloading via GitHub and do **MAKE SURE** you do this **AFTER** the [contest status](status.html) has changed to [open](#open). Jump to: [top](#)
### Q 1.8: How can I avoid re-entering my UUID to mkiocccentry?
Because some people might want to submit more than one submission, an option to read the UUID from a file exists, so that you don't have to repeatedly copy and paste the UUID in. If the file is not a regular readable file or it does not have a valid UUID, you will be prompted as if you had not used the option. If you use the `-i answers` feature this will not be used as the UUID is included in the answers file. There are two ways to do this - it is purely a matter of preference. The first way is to put your UUID in a text file (the UUID by itself on a single line) with no spaces before or after it, and then run: ``` mkiocccentry -u uuid workdir topdir ``` where `uuid` is the file containing your UUID, `workdir` is the workdir and `topdir` is the topdir. The second way is to specify the UUID on the command line itself. For instance if your UUID was `test` (for test mode) you could do: ``` mkiocccentry -U test workdir topdir ``` See also the FAQ on "[the answers file](#answers_file)". Jump to: [top](#)
### Q 1.9: How can I avoid having to move or delete my submission directory for the same workdir?
If you wish to not have to worry about removing or moving the submission directory under the workdir, you may use the `-x` option to `mkiocccentry`. For instance, you can do: ``` mkiocccentry -x workdir topdir ``` and if the submission directory under workdir already exists it will be removed first so you do not have to do so. If for some reason your `rm` command cannot be found or does not exist you can specify the path by the `-r rm` option. Jump to: [top](#)
### Q 1.10: Can I download my submission tarball from the submit server?
We do not support this. If you need to verify your submission, then you can re-upload (while the contest is in open state) and verify the SHA256 checksum listed in the submission slot. Jump to: [top](#)
### Q 1.11: Can I delete a submission from the submit server?
We do not support this. Instead, please create an empty prog.c, copy the [example Makefile](next/Makefile.example) to your Makefile and add to the remarks.md: > Please ignore this submission. Jump to: [top](#)
### Q 1.12: What are the detailed recommendations for a submission Makefile?
We **recommend** AND **encourage** you to use the example Makefile, as the starting point for your submission's required `Makefile`: - [view example Makefile](%%REPO_URL%%/next/Makefile.example) - download example Makefile Feel free to modify the `Makefile` to suit your obfuscation needs. **Please** add a space between the `=` and the value of variables, in the `Makefile`, making sure that the `=` comes immediately after the name. See the example `Makefile` for examples. The rest of this section and its subsections will assume that you are using some variant of the example `Makefile`, again renamed as `Makefile`. We suggest that you compile your submission with a commonly available `-std=gnu17` (ISO C 2017 with GNU extensions) C compiler, via `clang(1)` and/or `gcc(1)`.
#### Default compiler flags
Unless you **clearly state** otherwise in your `remarks.md` file, **AND** put in your submission's `Makefile`, we **will** compile using `-std=gnu17 -O3`! It **is OK** if you need to require your submission to **NOT be** compiled using the default `-std=gnu17 -O3` settings. Simply **explain why** your submission should NOT be compiled using `-std=gnu17 -O3` in your `remarks.md` file, **AND** adjust your `Makefile` accordingly.

You really should **NOT** redefine `CC` because doing so makes it less portable. <-- **Hint!**

One reason that you might have to change the flags, is that the optimiser is known to break some programs, but there are certainly other possible valid reasons. Again, just update the `Makefile` and explain it in your `remarks.md`. See the [optimiser section](#optimiser) for details for changing optimiser flags. For more fun when it comes to optimisers breaking code, see [1986/marshall/compilers.html](1986/marshall/compilers.html).
#### Default compiler
**IMPORTANT NOTE**: The use of `-std=gnu17` does **NOT** imply the use of the `gcc` compiler! We often start by compiling using the **clang** C compiler instead. **PLEASE NOTE**: in macOS, the compiler `gcc` found at `/usr/bin/gcc` is in truth the `clang` compiler, as `/usr/bin/gcc --version` will show!
#### C standard
You may change the standard under which your submission is compiled by modifying the `CSTD` Makefile variable. For example, to use `c99` instead: ``` CSTD= -std=c99 ```
#### Default optimisation level
You may change the level of optimization and compiler debug level that your submission is compiled with, by modifying the `OPT` Makefile variable. For example, to compile without optimization, and to include debug symbols: ``` OPT= -O0 -g3 ```
#### Compiler warnings
The default warning flags are set via the `CWARN` variable, as shown in the example `Makefile`: ``` # Common C compiler warning flags # CWARN= -Wall -Wextra ${CSILENCE} ${CUNKNOWN} ``` For details on `CSILENCE` and `CUNKNOWN`, see the [section on disabling warnings](#disabling-warnings).
##### The `-Weverything` option
We do **NOT** recommend that you put the use of `-Weverything` into your submission's `Makefile` for the reasons cited there. This goes even if your version does not trigger a warning as some other version might! On the other hand, if `${CC}` has "`clang`" in the name, the example `Makefile` will automatically enable `-Weverything`, so you might have to use `-Wno-foo` options anyway, as detailed below. If "`clang`" is NOT in `${CC}`, the `CWARN` variable will not be further modified. There is no real penalty for compiler warnings. Sometimes compiler warnings cannot be helped: especially in the case of obfuscated C. :-) So if you cannot easily get rid of a compiler warning, try not to fret too much. We **LIKE** code that has a minimum of warnings, especially under the more strict ` -Wall -Wextra -pedantic` mode: ``` CWARN= -Wall -Wextra -pedantic ``` The two previous guidelines might be thought by some as being somewhat contradictory. Isn't life, and isn't trying to satisfy "contradictory customer requirements" all too often like that? :-) Try to minimize warnings if you can. If you manage to produce very few warnings, or perhaps no warnings at all under the `-Wall -Wextra -pedantic` mode, then by all means brag about it in your `remarks.md` file **AND BE SURE TO TELL US** the OS, OS version, compiler and compiler version in which you observed this occurring (in case our OS and compiler produces a different result: so your submission won't be penalized for not meeting your claims). On the other hand, some warnings cannot be disabled and are enabled by compilers without any warning option specified. These are sometimes inevitable in obfuscated code and even in some non-obfuscated code, and you should not worry about this, though it might be worth pointing out. For instance, some compilers like to warn about use of pointers as arrays, which seems to be dubious, as it obviously can't (always) be avoided, being a big part of C, so you should not worry about this either; this is the warning `-Wunsafe-buffer-usage` and the way to disable it is `-Wno-unsafe-buffer-usage`.
#### Disabling warnings

If you do have to disable warnings due to `-Weverything` automatically being included, you might wish to state this fact in your `remarks.md` file. And even without `-Weverything` there can be warnings, as noted above.

If your submission issues lots of warnings but is otherwise marvelously obfuscated in multiple levels, don't worry about it. Nevertheless, be sure that the warnings do not constitute a potential "**show stopper**" compiler problem. Be sure that compilers such as both `gcc` and `clang` won't produce a compiler **error** and refuse to compile your code: unless for some reason that is what you intend to happen in which case document that too in your `remarks.md` file. :-) All other things being equal, a program that must turn off fewer warnings will be considered better, for certain values of better. To turn off a compiler warning, in your submission's `Makefile`, try something such as: ``` CSILENCE= -Wno-some-thing -Wno-another-thing ```

For instance:

``` CSILENCE= -Wno-parentheses -Wno-binding-in-condition -Wno-misleading-indentation ```
#### Defining macros in the Makefile
If you need to define something on the compile line, use the `CDEFINE` Makefile variable. For example: ``` CDEFINE= -Dfoo -Dbar=baz ``` **NOTE**: just because we offer a default way to use the `-D` option, we still do not like excess use of `-D` to get past size limits, especially since you could use `#define` in your code instead.
#### Include files in the Makefile
If you need to include a file (as in `#include`) on the command line, use the `CINCLUDE` Makefile variable. For example: ``` CINCLUDE= -include stdio.h ```
#### Magic in the Makefile
If you need to add other "**magic**" flags to your compile line, use the `COTHER` Makefile variable. For example: ``` COTHER= -fno-math-errno ``` **NOTE**: **We only recommend using "_magic_" flags if _BOTH_ `gcc` _and_ `clang`** support it. Again, please note that in macOS, `/usr/bin/gcc` is actually `clang`!
#### The clobber rule
When `make clobber` is invoked, we request that submissions be restored to their original submission state. For example, any temporary files (**including** the compiled program(s)) created during the build process, or during execution should be removed by the `clobber` rule. In other words, the only things that should be in the directory after running `make clobber` is what is in your submission tarball itself. While people are free to manage their submission under `git(1)` or even use a GitHub repo, dot-files and dot-directories such as `.git` are not allowed in a submission. The `mkiocccentry(1)` tool will ignore dot-files and dot-directories (such as `.vimrc`, `.bashrc`, `.git` and `.github`) and not put them in the submission's compressed tarball. So while you may use such files and directories to help develop your submission, they won't be included when you run the `mkiocccentry(1)` tool. Even if you did manage to get dot files or dot directories in the tarball somehow, `txzchk(1)` will flag it as an error. When the judges run `txzchk(1)` on the uploaded submission compressed tarball, if anything is wrong, for instance if you "sneak in" any dot files or dot directories, the submission **WILL BE REJECTED** for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-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. Of course if you do use GitHub to work on your submission, you might want to make the repo private so you don't reveal who you are. :-)

In other words, make **SURE** you keep anonymous who submitted the code!

Please do **NOT** use these tools to help with the `clobber` rule! For instance, do **NOT** use `git clean`! Not only does this depend on the user having `git(1)` but it also does not account for the submission tarballs. Even worse is when someone does have it in a `git(1)` repo it will remove files that are not under `git(1)` control! Instead, see the `clobber` rule in the example Makefile to see how to manage this.

In other words, for `make clobber`, do something like: ``` clobber: ${RM} -f foo bar baz ``` and **NOT** something like this: ``` # do NOT do this! clobber: -git clean -f # WRONG !!! ``` And do **NOT** use `git` for any other `Makefile` rule either. **NOTE**: `mkiocccentry(1)` will directly run `make clobber` in the submission directory. And although it is not an error if this fails, if it fails because the Makefile does not have a clobber rule, it will be flagged by `mkiocccentry(1)` (you may ignore this but it does put you at a risk of violating the rules). Jump to: [top](#)
### Q 1.13: May I use GitHub or other services to develop my submission?
While you may use your own git server or a publicly available service to develop your submission, we **DISLIKE** submissions that require it. What's more, since it would possibly not be anonymous it would break the rules as you are **NOT** allowed to reveal who you are. Jump to: [top](#)
## Section 2: IOCCC Judging process
Jump to: [top](#)
### Q 2.0: What is the best way to ask a question about the IOCCC rules, guideline and tools?
We realise that the [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html) and the [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry) can be confusing or even seem overwhelming to some people. The [IOCCC judges](judges.html) do welcome questions about the IOCCC and will be **happy to help**. Chances are, if you have a question, there are a number of other people who have similar questions. So we recommend that you first view the [GitHub discussions for this repo](https://github.com/ioccc-src/winner/discussions) to see if someone else asked it already. Feel free to join in on such a discussion, even if to just say: > I have this question too. Feel free to provide additional feedback in the existing discussion as needed. **BTW**: If your question is just about the [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry), please view the [mkiocccentry repo discussions](https://github.com/ioccc-src/mkiocccentry/discussions) instead. If you do not find a suitable open discussion, please consider opening a [new IOCCC winner repo discussion](https://github.com/ioccc-src/winner/discussions/new/choose) with your question. Doing this may be of help to others with a question similar to yours. **BTW**: If your question is just about the [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry/discussions), and you do not see a suitable open discussion over there, then please consider opening a [new mkiocccentry discussion](https://github.com/ioccc-src/mkiocccentry/discussions/new/choose) over there. If you do not feel, for some reason, comfortable asking your question in public (although we hope you consider asking it in public for the benefit of others), then use the [How to contact the IOCCC](contact.html) information to ask a private question. **IMPORTANT NOTE**: When you ask your question (in public or as a private question) **PLEASE** try to **NOT** discuss detailed information about any pending submission. Try to ask for question in a more generic way as this will help others with a similar question and this will not **give away** what you might be doing with your submission. If the [IOCCC judges](judges.html) truly need more information, they will ask (either in public or suggest a private conversation). Again, **please** don't hesitate to ask: Your question may be something that others are wondering about as well! See also the FAQ on "[rules, guidelines, tools feedback](#feedback)". Jump to: [top](#)
### Q 2.1: How can I comment or make a suggestion on IOCCC rules, guidelines and tools?
The [IOCCC judges](judges.html) to welcome feedback on the [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html), and on the [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry). To comment on the [IOCCC rules](next/rules.html) or the [IOCCC guidelines](next/guidelines.html) please view the [GitHub discussions for this repo](https://github.com/ioccc-src/winner/discussions). If there is an on-going discussion that seems relevant to what you have to say, consider adding comments to that particular discussion. Otherwise consider opening a [new IOCCC repo discussion](https://github.com/ioccc-src/winner/discussions/new/choose). To comment on [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry), please view the [mkiocccentry repo discussions](https://github.com/ioccc-src/mkiocccentry/discussions). If there is an on-going discussion that seems relevant to what you have to say, consider adding comments to that particular discussion. Otherwise consider opening a [new mkiocccentry discussion](https://github.com/ioccc-src/mkiocccentry/discussions/new/choose). Jump to: [top](#)
### Q 2.2: Are there any compiler warnings that I should not worry about in my submissions?
There are unfortunately some warnings that cannot be disabled; they are always enabled whatever warning options you have enabled. Also, there is a warning that is enabled whenever you use a pointer as a buffer, saying it is unsafe buffer usage, even when it is not. This might be enabled by `-Weverything` but it might not be but it is not detrimental to your submission if you disable this, which you can do by specifying `-Wno-unsafe-buffer-usage`. So in short, no you should not worry about these as they are sometimes inevitable in obfuscated code and even non-obfuscated code. If you *can* work past this it might be good but this is not something that should be worried about too much as this is on the compiler developers, not you. Of course if you do work past it feel free to brag, though **BE SURE TO TELL US** the OS, OS version, compiler and compiler version. For more details on why we use `-Weverything` in Clang see the FAQ on "[-Weverything](#weverything)". Jump to: [top](#)
### Q 2.3: What types of entries have been frequently submitted to the IOCCC?
There are types of entries that are frequently submitted to the IOCCC. While we **do not wish to prevent** people from sending a submission to the IOCCC on a frequently submitted theme, we do wish to provide a **fair warning** to those who do. #### Fair warnings on frequently submitted themes: **IMPORTANT HINT**: It is **not fatal** to send in those types of entries, it is just **HARDER to win** with such a submission. A submission on a frequently submitted theme will have to do something in a **really unique AND interesting way** to even make it into the final judging rounds. It will have to compete with previous IOCCC winners based on the same theme. **IMPORTANT HINT**: If you really wish send in a submission on a frequently submitted theme, be sure that it is obfuscated in several new and novel ways. **IMPORTANT HINT**: Be sure to **clearly explain** near the beginning of your `remarks.md` file, see the FAQ on "[remarks.md](#remarks_md)", **why you are submitting an entry based on a frequently submitted theme** and **how compares with previous IOCCC winners** of the same theme. #### Examples of frequently submitted themes ##### Maze generator - [1985/shapiro](1985/shapiro/index.html) - [1991/buzzard](1991/buzzard/index.html) - [1995/cdua](1995/cdua/index.html) - [1995/dodsond2](1995/dodsond2/index.html) - [1998/bas1](1998/bas1/index.html) ##### Tic-Tac-Toe/Noughts and Crosses/Xs and Os game - [1991/westley](1991/westley/index.html) - [1996/jonth](1996/jonth/index.html) - [2020/carlini](2020/carlini/index.html) ##### Solitaire/Othello game - [1987/lievaart](1987/lievaart/index.html) - [1994/dodsond1](1994/dodsond1/index.html) ##### Generating small primes (below is the list of all prime related winning entries) - [1985/august](1985/august/index.html) - [1988/applin](1988/applin/index.html) - [1994/weisberg](1994/weisberg/index.html) - [1995/makarios](1995/makarios/index.html) - [1996/dalbec](1996/dalbec/index.html) - [2000/bellard](2000/bellard/index.html) ##### Self-reproducing program - [1990/scjones](1990/scjones/index.html) - [1994/smr](1994/smr/index.html) - _do not claim your program is the smallest without seeing this entry_! - [2000/dhyang](2000/dhyang/index.html) - _this entry set a high bar for entries of this theme_ ##### Entries that just print "Hello, world!" - [1984/anonymous](1984/anonymous/index.html) - [1985/applin](1985/applin/index.html) - [1986/applin](1986/applin/index.html) - [1986/holloway](1986/holloway/index.html) - [1989/jar.1](1989/jar.1/index.html) - [1992/lush](1992/lush/index.html) - [2000/tomx](2000/tomx/index.html) ##### Entries that use some complex state machine/table to print something - [1988/isaak](1988/isaak/index.html) - [1988/phillipps](1988/phillipps/index.html) - [2018/ciura](2018/ciura/index.html) - [2018/giles](2018/giles/index.html) ##### ROT13 - [1985/sicherman](1985/sicherman/index.html) - [1989/westley](1989/westley/index.html) - [1990/dg](1990/dg/index.html) - [1991/fine](1991/fine/index.html) ##### **pi** or **e** computation - [1986/august](1986/august/index.html) - [1988/robison](1988/robison/index.html) - [1988/westley](1988/westley/index.html) - [1989/roemer](1989/roemer/index.html) #### The above list of frequently submitted themes is not exhaustive #### Some final thoughts on frequently used themes While it is possible to win a new IOCCC with one of these **frequently submitted** types of entries, level of the competition from previous IOCCC entries make it more challenging to be successful. It is also important to note that the [guidelines](next/guidelines.html) often state something along the lines of: > We tend to dislike programs that: are similar to previous winning entries. **FAIR WARNING**: Be sure to **clearly explain** near the beginning of your `remarks.md` file, see the FAQ on "[remarks.md](#remarks_md)", **why you are submitting an entry based on a frequently submitted theme** and **how compares with previous IOCCC winners** of the same theme. Jump to: [top](#)
### Q 2.4: How did an entry win the IOCCC that breaks Rule 2 - Size restrictions?
As entries have been fixed it is entirely possible that some of the entries no longer fit within the year's size restrictions. Invariably the length of columns and/or number of rows have also changed. The `winner.orig.c` file contains the original source code that was subjected to rule 2 of the given IOCCC. You may also wish to see the [archive](archive) directory where you can find all the original winning entries as compressed tar files for a given year. In some cases the entry may have abused rule 2 and declared an "abuse of the rules" (although now blatant abuse of the rules to get around rule 2 size limits is discouraged). Jump to: [top](#)
### Q 2.5: How many submissions do the judges receive for a given IOCCC?
By tradition, we do not say. Jump to: [top](#)
### Q 2.6: How much time does it take to judge the contest?
It takes a fair amount of time to setup, run, respond to messages, process entries, review entries, trim down the set entries to a set of winning entries, doing the write-up of the entries, announcing the entries, reviewing final edits of the winning entry set, posting the winning entries, being flamed :-), tell folks who send in late entries to wait until the next contest, etc... It takes a few weekends and a number nights of study and work ... which is hard given that we are busy with many other activities as well. Note that we do not contact the author if an entry does not compile or does not work as advertised; we might attempt to fix obvious compilation problems or incompatibilities, but no more than that - so be sure that your entry does work on at least a couple different platforms, at least one of them being UNIX or SUS-conforming. See the FAQ on "[SUS](#SUS)" for more information. Jump to: [top](#)
### Q 2.7: How many judging rounds do you have?
Are you trying to trick us? :-) By tradition, we do not say how many judging rounds we have in a given IOCCC. We often report when the IOCCC judges start the 1st round, and then usually report when the IOCCC judges start near final judging rounds, and sometimes we also report when we enter what we believe is the final judging round, so you may guess that we have at least 3 rounds. :-) The actual number of rounds is certainly more than 3. Jump to: [top](#)
### Q 2.8: Why do some IOCCC entries receive the Grand Prize or Best of Show award?
In some years, the IOCCC judges discover a truly amazing IOCCC entry that stands out among all of the other IOCCC entries received that year. For such an IOCCC entry, the IOCCC judges award a "`Grand Prize`" or "`Best of Show award`". In 1984-1987, the "`Grand Prize`" winning entries are: - [1984/mullender](1984/mullender/index.html) - [1985/shapiro](1985/shapiro/index.html) - [1986/wall](1986/wall/index.html) - [1987/lievaart](1987/lievaart/index.html) - [1991/westley](1991/westley/index.html) Starting from 1988, the entry we liked the most in that year is called "`Best of Show`". Here are the "`Best of Show`" entries: - [1988/applin](1988/applin/index.html) - [1989/jar.2](1989/jar.2/index.html) - [1990/theorem](1990/theorem/index.html) - [1991/brnstnd](1991/brnstnd/index.html) - [1992/vern](1992/vern/index.html) - [1996/august](1996/august/index.html) - [1998/banks](1998/banks/index.html) - [2000/jarijyrki](2000/jarijyrki/index.html) - [2001/jason](2001/jason/index.html) - [2004/gavin](2004/gavin/index.html) - [2005/persano](2005/persano/index.html) - [2006/toledo2](2006/toledo2/index.html) - [2011/akari](2011/akari/index.html) - [2013/cable2](2013/cable2/index.html) - [2018/mills](2018/mills/index.html) - [2020/carlini](2020/carlini/index.html) In 1993, 1994 and 1995 the judges were unable to select a clear overall winning entry. So to give a nod to the entry that had the highest approval ranking from the judges, they used the following awards: - [1993/rince](1993/rince/index.html) - `Most well rounded` - [1994/shapiro](1994/shapiro/index.html) - `Most well rounded obfuscation` - [1995/leo](1995/leo/index.html) - `Best use of obfuscation` These could be considered the '`best entry`' for those years with 1 or more other entries that came in close behind. Jump to: [top](#)
### Q 2.9: How are winning IOCCC entries announced?
Once the [IOCCC](index.html) closes, the judges will: * Judge the submissions. * Select the [winning entries](years.html) and announce them on a live show on the [Our Favorite Universe](https://www.youtube.com/@OurFavoriteUniverse) YouTube channel. * At the end of the live show on the [Our Favorite Universe](https://www.youtube.com/@OurFavoriteUniverse) YouTube channel, the winning code will be pushed to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner). A few moments later, GitHub will render the updated [Official IOCCC website](index.html). * Update the [IOCCC news](news.html) page, also by updating this repo. * We will announce via the [@IOCCC mastodon -feed](https://fosstodon.org/@ioccc) that the source for new winning entries has been uploaded. * After a few days, the longer [Our Favorite Universe](https://www.youtube.com/@OurFavoriteUniverse) show will be segmented into segments of a few minutes in length, one for each winning entry. Then the [Official IOCCC website](index.html) will be updated so each new winning entry will be updated with a link to their specific announcement segment on the [Our Favorite Universe](https://www.youtube.com/@OurFavoriteUniverse) YouTube channel. Jump to: [top](#)
### Q 2.10: Why don't you publish submissions that do not win?
Because the publication on the IOCCC site **_IS_** the award! Anyone is free to put their IOCCC hopefuls, lookalikes and/or entries that do not win on their web page for everyone to see. Jump to: [top](#)
## Section 3: The mkiocccentry toolkit: finer details
Jump to: [top](#)
### Q 3.0: How can I validate my submission tarball?
The tool that validates submission tarballs can be obtained from the [IOCCC mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). The `mkiocccentry` tool itself will run the validator **after** forming the tarball. However, you may wish to manually validate the tarball. The tool that does this is `txzchk`. If you wish to validate the tarball without running the `mkiocccentry(1)` tool, for instance the tarball `submit.00000000-0000-4000-0000-000000000000-2.1720636351.txz` you can, after installing the tools, do: ``` txzchk submit.00000000-0000-4000-0000-000000000000-2.1720636351.txz ``` Assuming that the tarball exists and is valid, you should see no output. If you wish to see the contents, for instance like `mkiocccentry(1)` does, you could do: ``` txzchk -v 1 submit.00000000-0000-4000-0000-000000000000-2.1720636351.txz ``` As the [guidelines state](next/guidelines.html#txzchk), it is beyond the scope of this document to discuss the many tests that `txzchk(1)` runs; if you must know we refer you to the [source code](https://github.com/ioccc-src/mkiocccentry/blob/master/txzchk.c). Jump to: [top](#)
### Q 3.1: What is the `fnamchk` tool?
This tool, which is in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), validates the directory name of your submission. Rather than `mkiocccentry` running this tool manually, `txzchk`'s algorithm uses the output of this tool. If you wish to validate your tarball filename manually, you can do so. For instance: ``` fnamchk submit.00000000-0000-4000-0000-000000000000-2.1720636351.txz ``` Assuming everything is OK, it would show: > `00000000-0000-4000-0000-000000000000-2` See also the FAQ on "[validating your submission tarball](#txzchk)" for more information. Jump to: [top](#)
### Q 3.2: How can I validate my submission directory?
If you want to validate your submission directory manually, including but not limited to the `.auth.json` and `.info.json` files, you should use `chksubmit(1)` from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). The `chksubmit(1)` tool runs a variety of checks on your submission directory, including, but not limited to, using the [jparse API](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3) to validate the two IOCCC specific JSON files (as valid JSON) and additional checks on those files as well. An important thing that it does is verify that your files are the right permissions and that the manifest in the `.info.json` files match what is in the directory. What all the checks are is out of scope of this document; if you wish to know we recommend you read the [source code](https://github.com/ioccc-src/mkiocccentry/blob/master/chksubmit.c). **NOTE**: the IOCCC [jparse API](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3) is a synced copy of the [official jparse repo](https://github.com/xexyl/jparse) _at the time of the contest open date_. See the FAQ on "[.auth.json](#auth_json)" and FAQ on "[.info.json](#info_json)" for more details on the two required and very important JSON files. The `chksubmit(1)` tool accepts a single arg, a directory that **MUST** have the two JSON files, `.auth.json` and `.info.json` as well as the `prog.c`, `Makefile` and `remarks.md` files along with all the other files listed in the `.info.json` manifest. (Okay there is an option to skip files but this is for the judges **ONLY**; use of this option to validate your submission puts you at a great risk of violating [Rule 4 - Required files](next/rules.html#rule4-required-files), or [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)!). As an example, if your submission directory is `00000000-0000-4000-0000-000000000000-3/` then you should run the following command: ``` chksubmit 00000000-0000-4000-0000-000000000000-3 ``` If there is a [JSON](https://www.json.org/json-en.html) issue detected by the `jparse(3)` API (i.e. it is not valid JSON) it is an error and `chksubmit(1)` will report this, exiting with a non-zero exit code. If the parsing is OK (i.e. valid JSON) but there is an issue in one or both of the [JSON](https://www.json.org/json-en.html) files in **the context of the IOCCC**, it will report this as an **error**. It also does, as briefly noted above, other checks. If `chksubmit(1)` fails to validate your submission directory your submission **WILL** be **REJECTED**! This is why you **MUST** make sure you use the `mkiocccentry(1)` tool to form your submission directory. See the FAQ on "[.auth.json](#auth_json)" and the FAQ on "[.info.json](#info_json)" as well as [Rule 4 - Required files](next/rules.html#rule4-required-files), and [Rule 17 - Use mkiocccentry](next/rules.html#rule17-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 of `chkentry(1)` when validating a directory; `chkentry(1)` is for the judges and is what was used in IOCCC28. For IOCCC29 and beyond, `mkiocccentry(1)` uses `chksubmit(1)` and so should you. Jump to: [top](#)
### Q 3.3: What is a `.auth.json` file?
This file is constructed by the `mkiocccentry(1)` **prior to** forming the xz compressed tarball of your submission. The `.auth.json` file contains information about the author or authors of the submission, in JSON format. In order of the file's contents we describe each required field, below: - `no_comment` (double quoted string) * We can provide `no comment` about `no_comment` other than to state that unless `no_comment` matches this quote: > "mandatory comment: because comments were removed from the original JSON spec" your submission **WILL BE** rejected! Are we suggesting that removing comments from the JSON spec was a mistake? > "You might very well think that; but of course I couldn't possibly comment." -- Francis Urquhart - `IOCCC_auth_version` (double quoted string) * The current version of the `.auth.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `.auth.json` version, defined as `AUTH_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `IOCCC_contest` (double quoted string) * Which contest number this is (e.g. 1 for 1984, 2 for 1985, 27 for 2020). **IMPORTANT:** this **MUST** match **THIS** IOCCC's contest value, defined as `IOCCC_CONTEST` 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/). If this is not the case your submission **WILL BE** rejected! - `IOCCC_year` (number) * The year this contest was run in. **NOTE:** sometimes an IOCCC year runs into another year and the contest year might not match when it ends. **IMPORTANT:** this **MUST** match **THIS** IOCCC's contest, defined as `IOCCC_YEAR` 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/). If this is not the case your submission **WILL BE** rejected! - `mkiocccentry_version` (double quoted string) * The version of `mkiocccentry` that formed this `.auth.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `mkiocccentry` version, defined as `MKIOCCCENTRY_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `chksubmit_version` (double quoted string) * The version of `chksubmit` that was used to validate the submission directory, including the `.auth.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `chksubmit` version, defined as `CHKENTRY_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `fnamchk_version` (double quoted string) * The version of `fnamchk` that `txzchk` uses to validate the filename of the xz compressed tarball. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `fnamchk` version in order for it to be valid. If this is not the case your submission **WILL BE** rejected! - `IOCCC_contest_id` (double quoted string) * The IOCCC contestant ID used as a username in the form of **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 - Use mkiocccentry](next/rules.html#rule17-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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `tarball` (double quoted string) * The xz compressed tarball filename. **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 - Use mkiocccentry](next/rules.html#rule17-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 - Use mkiocccentry](next/rules.html#rule17-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 tarball, this will be flaggd. - `submit_slot` (number) * The submission number. **IMPORTANT:** this **MUST** be within the range of 0 **THROUGH** `MAX_SUBMIT_SLOT` (see [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/)). If this is not the case you stand a great risk of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `author_count` (number) * How many authors this submission has. **IMPORTANT:** this **MUST** be within the range of 1 **THROUGH** `MAX_AUTHORS` (see [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/)). If this is not the case you stand a great risk of having your submission rejected for violating the [Rules](next/rules.html)! Moreover, if the `author_count` is inconsitent with how many authors are in the `authors` array your submission **will be** invalid. - `test_mode` (boolean) * `true` if the `test` ID was used to form the tarball, else `false`. **NOTE:** if `true` then this may **NOT** be submitted to the contest! Please do **NOT** email the [Judges](judges.html) your submission! Next, the JSON `authors` **array** holds the following information about the author(s) of the submission: - `name` (double quoted string) * The **name** of this author. - `location_code` (double quoted string) * The **location code** of this author (an ISO 3166-1 2 character code). See for a list of valid codes. **NOTE:** in `mkiocccentry` use `XX` if you want your location to be anonymous. - `email` (`null` or double quoted string) * The **email** of this author in the form of `x@y`, or `null` if not provided. - `url` (`null` or double quoted string) * The primary **URL** of this author, or `null` if not provided. * The URL must start with `http://` or `https://` and have more text after it; we do not even try and detect a hostname. - `alt_url` (`null` or double quoted string) * The **alt URL** of this author, or `null` if not provided. * The URL must start with `http://` or `https://` and have more text after it; we do not even try and detect a hostname. - `mastodon` (`null` or double quoted string) * The Mastodon handle of this author in the form of `@user@domain`, or `null` if not provided. See the FAQ on "[Mastodon](#try_mastodon)" for more information. - `github` (`null` or double quoted string) * The **[GitHub](https://github.com) account** of this author in the form of `@user`, or `null` if not provided. - `affiliation` (`null` or double quoted string) * This author's **affiliation**, if any, or `null` if not provided. **IMPORTANT:** if provided, the length of the **affiliation** **MUST** be within the range of 1 **THROUGH** `MAX_AFFILIATION_LEN` (see [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/)). If this is not the case you stand a great risk of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). **NOTE:** an **affiliation** does **NOT** have any affect on whether you will win or not. - `past_winning_author` (boolean) * `true` if this author claims to have won a past IOCCC, `false` if this author has **NOT** won before. **NOTE:** this has **NO** effect on whether you will win or not. - `default_handle` (boolean) * `true` if this default handle was accepted, `false` if one is provided by this author. - `author_handle` (double quoted string) * This author's handle (custom or default provided). **NOTE:** if you have won before, we **ENCOURAGE** you to use the same handle of your previous winning entries, to help in organising the [authors.html](authors.html) page and the author JSON file. See the FAQ on "[author handle](#author_handle_faq)" and the FAQ on "[author_handle.json](#author_json)" for more information. - `author_number` (number) * This author number in the `authors` array. After the `authors` **array** the remaining of a `.auth.json` file holds: - `formed_timestamp` (number) * Seconds since epoch when `.auth.json` was formed (see `gettimeofday(2)`). See also the FAQ on "[.info.json](#info_json)" for more information. **IMPORTANT:** this **MUST** be greater than or equal to `MIN_TIMESTAMP` (see [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/)). If this is not the case your submission **WILL BE** rejected. - `formed_timestamp_usec` (number) * Microseconds since the tstamp (seconds since epoch when `.auth.json` was formed - see `gettimeofday(2)`) second. **IMPORTANT:** this **MUST** be within the range `MIN_FORMED_TIMESTAMP_USEC` **THROUGH** `MAX_FORMED_TIMESTAMP_USEC` and is validated by `test_formed_timestamp_usec()` in [soup/entry_util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.c) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case `chksubmit(1)` will report an **error** and your submission **WILL BE** rejected! - `timestamp_epoch` (double quoted string) * `"Thu Jan 01 00:00:00 1970 UTC"` (`gettimeofday(2)` epoch). **IMPORTANT:** this **MUST** be `"Thu Jan 01 00:00:00 1970 UTC"` which is `#define`d as `TIMESTAMP_EPOCH` 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/). If this is not the case your submission **WILL BE** rejected! - `min_timestamp` (number) * Minimum number of second since epoch for **this** IOCCC. **IMPORTANT:** this **MUST** be >= `MIN_TIMESTAMP` defined 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/). If this is not the case your submission **WILL BE** rejected! This file will be validated with the `chksubmit(1)` tool and if there are any problems with it or the submission directory, **it is an error**. If there is an error the tarball will **NOT** be formed by `mkiocccentry`; otherwise the `txzchk(1)` tool will be executed on the tarball. This file will **NOT** be looked at unless the submission wins! Nonetheless, the file **MUST** be present in the submission directory and it **MUST** be valid JSON and it **MUST** pass all IOCCC semantics checks and all other checks `chksubmit(1)` perform. `chksubmit(1)` is used by `mkiocccentry(1)` and the judges will use it on the submission directory as part of the judging process. At the risk of stating the obvious, if your `.auth.json` file is invalid JSON or is reported invalid by `chksubmit(1)`, or if your submission directory is reported invalid by `chksubmit(1)`, your submission will almost certainly be rejected for violating the [Rules](next/rules.html) and in particular [Rule 4 - Required files](next/rules.html#rule4-required-files), and [Rule 17 - Use mkiocccentry](next/rules.html#rule17-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 not a string or is the wrong string. Another obvious example is when things are 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(1)`) your submission would be rejected for violating [Rule 4 - Required files](next/rules.html#rule4-required-files), and [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry) and in particular because `chksubmit(1)` would not validate the `.auth.json` file (and maybe other things too). If you wish to **verify** that your `.auth.json` file is valid **JSON** then see the FAQ on "[validating JSON documents](#validating_json)". Jump to: [top](#)
### Q 3.4: What is a `.info.json` file?
This file is constructed by the `mkiocccentry(1)` **prior to** forming the xz compressed tarball of your submission. The `.info.json` file contains information about the submission, in JSON format. The JSON `manifest` array contains information about the files of the submission, **including** the **mandatory** `.auth.json` file, the **mandatory** `remarks.md` file, and the **mandatory** C source file. See the FAQ on "[.auth.json](#auth_json)" and the FAQ on "[remarks.md](#remarks_md)" for more information. In order of the file's contents we describe each required field, below: - `no_comment` (double quoted string) * We can provide `no comment` about `no_comment` other than to state that unless `no_comment` matches this quote: > "mandatory comment: because comments were removed from the original JSON spec" your submission **WILL BE** rejected! Are we suggesting that removing comments from the JSON spec was a mistake? > "You might very well think that; but of course I couldn't possibly comment." -- Francis Urquhart - `IOCCC_info_version` (double quoted string) * The current version of the `.info.json` files. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `.info.json` version, defined as `INFO_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `IOCCC_contest` (double quoted string) * Which contest number this is (e.g. 1 for 1984, 2 for 1985, 27 for 2020). **IMPORTANT:** this **MUST** match **THIS** IOCCC's contest value, defined as `IOCCC_CONTEST` 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/). If this is not the case your submission **WILL BE** rejected! - `IOCCC_year` (number) * The year this contest was run in. **NOTE:** sometimes an IOCCC year runs into another year and the contest year might not match when it ends. **IMPORTANT:** this **MUST** match **THIS** IOCCC's contest, defined as `IOCCC_YEAR` 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/). If this is not the case your submission **WILL BE** rejected! - `mkiocccentry_version` (double quoted string) * The version of `mkiocccentry` that formed this `.auth.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `mkiocccentry` version, defined as `MKIOCCCENTRY_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `iocccsize_version` (double quoted string) * The version of `iocccsize` that was used for this `.info.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `iocccentry` version, defined as `IOCCCSIZE_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `chksubmit_version` (double quoted string) * The version of `chksubmit` that was used to validate the submission directory, including the `.info.json` file. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `chksubmit` version, defined as `CHKENTRY_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `fnamchk_version` (double quoted string) * The version of `fnamchk` that `txzchk` uses to validate the filename of the xz compressed tarball. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `fnamchk` version, defined as `FNAMCHK_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `txzchk_version` (double quoted string) * The version of `txzchk` used to validate the xz compressed tarball. **IMPORTANT:** this **MUST** be >= **THIS** IOCCC's `txzchk` version, defined as `TXZCHK_VERSION` in [soup/version.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/version.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case your submission **WILL BE** rejected! - `IOCCC_contest_id` (double quoted string) * The IOCCC contestant ID used as a username in the form of **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `submit_slot` (number) * The submission number. **IMPORTANT:** this **MUST** be within the range of 0 **THROUGH** `MAX_SUBMIT_SLOT` (see [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/)). If this is not the case you stand a great risk of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `title` (double quoted string) * A short name (length >= 1 **THROUGH** `MAX_TITLE_LEN`, defined 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/)) that 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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `abstract` (double quoted string) * A one line summary of your submission, with a length of 1 **THROUGH** `MAX_ABSTRACT_LEN`, defined 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/)) The `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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `tarball` (double quoted string) * The xz compressed tarball filename. **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 - Use mkiocccentry](next/rules.html#rule17-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 - Use mkiocccentry](next/rules.html#rule17-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 tarball, this will be flaggd. - `rule_2a_size` (number) * The size calculated of [Rule 2a - Gross Size](next/rules.html#rule2a-gross-size). **IMPORTANT:** if this violates [Rule 2a](next/rules.html#rule2a) you stand a great chance of having your submission rejected for violating the [Rules](next/rules.html)! - `rule_2b_size` (number) * The size calculated of [Rule 2b - Net Size](next/rules.html#rule2b-net-size). **IMPORTANT:** if this violates [Rule 2b Net Size](next/rules.html#rule2b-net-size) you stand a great chance of having your submission rejected for violating the [Rules](next/rules.html)! - `empty_override` (boolean) * `true` if user override warning of an empty source file, else `false`. - `rule_2a_override` (boolean) * `true` if user overrides warning of [Rule 2a - Gross Size](next/rules.html#rule2a-gross-size) violation, else `false`. **IMPORTANT:** if the [Rule 2a - Gross Size](next/rules.html#rule2a-gross-size) calculated size is **NOT** violated but this is `true` then you stand a good chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `rule_2a_mismatch` (boolean) * `true` if [Rule 2a - Gross Size](next/rules.html#rule2a-gross-size) calculated size is not the same as the file size. - `rule_2b_override` (boolean) * `true` if user overrides warning of [Rule 2b - Net Size](next/rules.html#rule2b-net-size) violation, else `false`. **IMPORTANT:** if the [Rule 2b - Net Size](next/rules.html#rule2b-net-size) calculated size is **NOT** violated but this is `true` then you stand a good chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry). - `trigraph_warning` (boolean) * `true` if `iocccsize` detects an unknown or invalid trigraph in `prog.c`, else `false`. - `ungetc_warning` (boolean) * `true` if `prog.c` triggered an `ungetc(3)` error, else `false`. - `Makefile_override` (boolean) * `true` if the user overrides any warnings about an incomplete/incorrect `Makefile` file, 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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `first_rule_is_all` (boolean) * This is ignored and will be removed for IOCCC29 and beyond. **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `found_all_rule` (boolean) * `true` if the `Makefile` file has an `all` rule, else `false`. **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `found_clean_rule` (boolean) * `true` if the `Makefile` file has a `clean` rule, else `false`. **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `found_clobber_rule` (boolean) * `true` if the `Makefile` file has a `clobber` rule, else `false`. **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `found_try_rule` (boolean) * `true` if the `Makefile` file has a `try` rule, else `false`. **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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! See the FAQ on "[Makefile](#makefile)" for more information. - `test_mode` (boolean) * `true` if the `test` ID was used to form the tarball, else `false`. **IMPORTANT:** if this is `true` then this may **NOT** be submitted to the contest! Please do **NOT** email the [Judges](judges.html) your submission! Next comes the `manifest` **array** which **MUST** have AT LEAST the following. The `mkiocccentry(1)` tool will write it in this order: - `info_JSON` (double quoted string) * This `MUST` be `".info.json"`, defined as `INFO_JSON_FILENAME` in [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and it is the `.info.json` file that `mkiocccentry` forms. See the FAQ on "[.info.json](#info_json)" for more information. **IMPORTANT:** if this is **NOT** the case you stand a great chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `auth_JSON` (double quoted string) * This `MUST` be `".auth.json"`, defined as `AUTH_JSON_FILENAME` in [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and it is the `.auth.json` file that `mkiocccentry` forms. See the FAQ on "[.auth.json](#auth_json)" for more information. **IMPORTANT:** if this is **NOT** the case you stand a great chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `c_src` (double quoted string) * This `MUST` be `"prog.c"`, defined as `PROG_C_FILENAME` in [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and 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 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `Makefile` (double quoted string) * This `MUST` be `"Makefile"`, defined as `MAKEFILE_FILENAME` in [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and is your `Makefile` file. See the FAQ on "[Makefile](#makefile)" for more information. **IMPORTANT:** if this is **NOT** the case you stand a great chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! - `remarks` (double quoted string) * This `MUST` be `"remarks.md"`, defined as `REMARKS_FILENAME` in [soup/entry_util.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.h) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/), and is your `remarks.md]` file. See the FAQ on "[remarks.md](#remarks_md)" for more information. **IMPORTANT:** if this is **NOT** the case you stand a great chance of having your submission rejected for violating [Rule 17 - Use mkiocccentry](next/rules.html#rule17-mkiocccentry)! The `manifest` **array** also **OPTIONALLY** has one or more of the field: - `extra_file` (double quoted string) * Any additional file that you need or want to include with your submission. **IMPORTANT:** this MUST **NOT** match a mandatory filename (see above list) and `chksubmit` will verify this for you; it is **ALSO** an **error** if the 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 - Use mkiocccentry](next/rules.html#rule17-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. Even so, the [Judges](judges.html) **WILL** extract the tarball and if a file listed in the manifest does not exist your submission will very likely be rejected for not being as documented! Finally, after the `manifest` **array**, the following fields **MUST** exist: - `formed_timestamp` (number) * Seconds since epoch when JSON (`.auth.json` or `.info.json`) file was formed (see `gettimeofday(2)`). **IMPORTANT:** this **MUST** be greater than or equal to `MIN_TIMESTAMP` (see [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/)). If this is not the case your submission **WILL BE** rejected. - `formed_timestamp_usec` (number) * Microseconds since the tstamp (seconds since epoch when `.auth.json` was formed - see `gettimeofday(2)`) second. **IMPORTANT:** this **MUST** be within the range `MIN_FORMED_TIMESTAMP_USEC` **THROUGH** `MAX_FORMED_TIMESTAMP_USEC` and is validated by `test_formed_timestamp_usec()` in [soup/entry_util.c](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/entry_util.c) in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/). If this is not the case `chksubmit(1)` will report an **error** and your submission **WILL BE** rejected! - `timestamp_epoch` (double quoted string) * `"Thu Jan 01 00:00:00 1970 UTC"` (`gettimeofday(2)` epoch). **IMPORTANT:** this **MUST** be `"Thu Jan 01 00:00:00 1970 UTC"` which is `#define`d as `TIMESTAMP_EPOCH` 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/). If this is not the case your submission **WILL BE** rejected! - `min_timestamp` (number) * Minimum number of second since epoch for **this** IOCCC. **IMPORTANT:** this **MUST** be >= `MIN_TIMESTAMP` defined 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/). If this is not the case your submission **WILL BE** rejected! This file will be validated with the `chksubmit(1)` tool and if there are any problems with it or the submission directory, **it is an error**. If there is an error the tarball will **NOT** be formed by `mkiocccentry`; otherwise the `txzchk(1)` tool will be executed on the tarball. When the [Judges](judges.html) use `chksubmit(1)` on your submission directory, if this JSON file is invalid JSON or does not match the requirements outlined above, or if any other is found, your submission **WILL BE** rejected. An obvious example where `chksubmit` would fail to validate `.info.json` is if there is a mismatch of type in the JSON file with what is expected, for instance, if in `.info.json` the `no_comment` that we chose to not comment on is not a string or is the wrong string. Another obvious example is when things are 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 - Use mkiocccentry](next/rules.html#rule17-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 FAQ on "[validating JSON documents](#validating_json)". Jump to: [top](#)
### Q 3.5: What is an `author_handle`?
An `author_handle` is string that refers to a given author and is unique to the IOCCC. Each author has exactly one `author_handle`. For each `author_handle`, there will be a JSON file of the form: `author/author_handle.json`. See the FAQ on "[fixing author information](#fix_author)" for information about how to update and/or correct IOCCC author information. See the FAQ on "[.auth.json](#auth_json)" for information about the contents of these JSON files and how they are used. See the FAQ on "[finding author handle](#find_author_handle)" for how to find your own _author_handle_. Because the `author_handle` is used to form a JSON filename, the string must be POSIX safe string plus the use of `+` (for technical reasons beyond this answer). In particular, the `author_handle` must be an ASCII string or 32 characters or less that matches this regexp: ``` ^[0-9A-Za-z][0-9A-Za-z._+-]*$ ``` Default `author_handle`'s do not have multiple consecutive `_` (underscore) characters. Nevertheless, multiple consecutive `_` (underscore) characters are allowed. Contest submitters who wish to override their default `author_handle` may do so, long as the ASCII string matches the regexp above AND so long as the length does not exceed the 32 ASCII characters (not including the terminating NUL byte). The `author_handle` is derived from the name of the author. While there is a algorithm that maps the name of the author (which can contain any UTF-8 characters) into a default `author_handle` string, those who submit an entry to the IOCCC are free to choose a different `author_handle` string if they so desire. An `author` who has won a previous IOCCC is encouraged to reuse their `author_handle` so that new winning entries can be associated with the same author. For an anonymous `author`, their handle is one of the form of `Anonymous_year` or `Anonymous_year.digits`. The latter form is in case there are more than one anonymous author in a given year. **NOTE**: even if the directory name is not `anonymous` the above rules apply as in in the case of [2005/anon](%%REPO_URL%%/2005/anon/anon.c). Anonymous `author_handle`'s match this regexp: ``` Anonymous_[0-9][0-9][0-9][0-9][.0-9]*$ ``` Jump to: [top](#)
### Q 3.6: What is an `author_handle.json` file and how are they used?
**TL:DR**: The contents of these JSON files contain the best known information about authors of IOCCC entries and is used to help form HTML files as well to contact an author. **NOTE**: tools to validate the `author_handle.json` files, which are only for winning authors, are in the works (which will be documented after they are developed). See the FAQ on "[author handles](#author_handle_faq)" for more information on author handles. The content of these JSON files are used by tools from the [bin directory](bin/index.html) to help build HTML content for the [official IOCCC website](index.html). For example, the `index.html` file for each IOCCC entry contains selected information about the authors. Tools from the [bin directory](bin/index.html) use the content of these JSON files to generate the `index.html` files for each IOCCC winning entry. Moreover, should the [IOCCC judges](judges.html) need to contact an authors of an IOCCC entry, they will consult the contents of the author's JSON file for ways to contact them. Each author of an IOCCC winning entry has their own `author_handle.json` file of the form `author/author_handle.json`. where _author_handle_ is an author handle. See FAQ on "[author handle](#author_handle_faq)" for more information about an author handles. #### `author_handle.json` JSON file contents The syntax of a `author_handle.json` follows the _So-called JSON spec_. See for information on the _So-called JSON spec_. A good way to understand the JSON file contents of a `author_handle.json` file is to look at an example, for instance the `author_handle.json` file for Yusuke Endoh, [author/Yusuke_Endoh.json](%%REPO_URL%%/author/Yusuke_Endoh.json). As of _Thu Nov 30 23:51:12 UTC 2023_, it was: ``` { "no_comment" : "mandatory comment: because comments were removed from the original JSON spec", "author_JSON_format_version" : "1.0 2023-06-10", "author_handle" : "Yusuke_Endoh", "full_name" : "Yusuke Endoh", "sort_word" : "endoh", "location_code" : "JP", "email" : "mame@ruby-lang.org", "url" : "https://mametter.hatenablog.com", "alt_url" : null, "deprecated_twitter_handle" : null, "mastodon" : "@mame@ruby.social", "mastodon_url" : "https://ruby.social/@mame", "github" : "@mame", "affiliation" : null, "winning_entry_set" : [ { "entry_id" : "2012_endoh1" }, { "entry_id" : "2012_endoh2" }, { "entry_id" : "2013_endoh1" }, { "entry_id" : "2013_endoh2" }, { "entry_id" : "2013_endoh3" }, { "entry_id" : "2013_endoh4" }, { "entry_id" : "2014_endoh1" }, { "entry_id" : "2014_endoh2" }, { "entry_id" : "2015_endoh1" }, { "entry_id" : "2015_endoh2" }, { "entry_id" : "2015_endoh3" }, { "entry_id" : "2015_endoh4" }, { "entry_id" : "2018_endoh1" }, { "entry_id" : "2018_endoh2" }, { "entry_id" : "2019_endoh" }, { "entry_id" : "2020_endoh1" }, { "entry_id" : "2020_endoh2" }, { "entry_id" : "2020_endoh3" } ] } ``` **NOTE**: if you need to just check the validity of a JSON document then see the FAQ on "[validating JSON documents](#validating_json)". Taking that FAQ in mind, if you wish to validate every JSON file in `author/` then you could do so like: ``` for auth in *.json; do jparse -q "$auth" || echo "$auth is invalid JSON" ; done ``` If you see any output then it will say which file or files are invalid JSON (this should not actually happen, however). See the FAQ on "[jparse](#jparse)", for now to location and/or install the `jparse(1)` command.
##### Walk through of an `author_handle.json` file
We now will walk thru the above JSON document looking at various JSON members: ##### no_comment ``` "no_comment" : "mandatory comment: because comments were removed from the original JSON spec" ``` Because the authors of the so-called JSON spec removed the ability to use comments in JSON (for reason(s) that seem to be less than credible), the IOCCC mandates this _JSON member_ be present in all IOCCC related JSON files. There **MUST** be one and only one `no_comment` _JSON member_ and the _JSON value_ **MUST** be the exact _JSON string_ as shown above. ##### author_JSON_format_version ``` "author_JSON_format_version" : "1.0 2023-06-10" ``` This _JSON member_ holds the format version of the `author_handle.json` JSON file. There **MUST** be one and only one `author_JSON_format_version` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_. This is **NOT** the version of the contents! When updating an `author_handle.json` JSON file, **DO NOT MODIFY author_JSON_format_version**! As of _Thu Nov 30 23:51:12 UTC 2023_, the _JSON value_ **MUST** be _"1.0 2023-06-10"_. The _author_JSON_format_version_ would only changed when the overall format of the these files is modified: and then only those who maintain the [official IOCCC website](index.html) would be the one to do this in conjunction with changes to [bin directory tools](bin/index.html). ##### author_handle ``` "author_handle" : "Yusuke_Endoh" ``` This _JSON member_ holds the author handle of the author. There **MUST** be one and only one `author_handle` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ that is also a value author handle. See FAQ on "[author handle](#author_handle_faq)" for more information about an author handles. Normally the _author_handle_ _JSON value_ should **NOT** be changed **unless there is a strong reason to do so**. If the _JSON value_ changes, then all of the `.entry.json` files for all of this authors winning IOCCC entries should also be changed. The _author_handle_ _JSON value_ must match the basename (without the leading path and without the trailing `.json`) of the `author_handle.json` file. So a change of _author_handle_ _JSON value_ would also require the `author_handle.json` file to also be renamed. ##### full_name ``` "full_name" : "Yusuke Endoh" ``` This _JSON member_ holds the full name of the author. There **MUST** be one and only one `full_name` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_. The full name of an author may use non-ASCII characters so long as the full name is properly encoded as a _JSON string_. ##### sort_word ``` "sort_word" : "endoh" ``` This _JSON member_ holds the string that will be used to sort the author. There **MUST** be one and only one `sort_word` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_. Moreover the string **MUST** be a lower case ASCII alphanumeric string that starts with a lower case ASCII letter. The _JSON value_ is used, for example, to place a reference to the author in the `/authors.html` file. Normally the `sort_word` _JSON member_ _JSON value_ is the last name of the author, translated into lower case ASCII alphanumeric string that starts with a lower case ASCII letter. If the author wishes to be found in the `/authors.html` file under a different string, such as if they wish to be listed under their first name or their username, then they may change this accordingly. ##### location_code ``` "location_code" : "JP" ``` This _JSON member_ holds the string that is the [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Decoding_table) of the author's location or country. There **MUST** be one and only one `location_code` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_. Moreover the string **MUST** be 2 character UPPER case ASCII alphabetic string that is **NOT** an Unassigned [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Decoding_table) value (not a 2 character symbol with a gray background on that Wikipedia table) The `soup/location` tool from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry), when run without arguments, will print the ISO 3166-1 alpha-2 codes that permitted, along with the location name. We use the term "location" (and not "country") because some of the ISO 3166-1 alpha-2 codes belong to locations that are not technically a country, such as "Antarctica" or a User-assigned code. If the author wishes to not specify a location, they should select **XX**. ##### email ``` "email" : "mame@ruby-lang.org" ``` This _JSON member_ holds the email address of the author, or is the value null. There **MUST** be one and only one `email` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. If the author wishes to not specify an email address, or if the email address is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "email" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### url ``` "url" : "https://mametter.hatenablog.com" ``` This _JSON member_ holds the URL of the author's home page. There **MUST** be one and only one `url` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. If the author wishes to not specify a URL or if the URL is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "url" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### alt_url ``` "alt_url" : null ``` This _JSON member_ holds an alternate or 2nd URL a home page for the author. There **MUST** be one and only one `alt_url` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. In some cases the author may wish to record a special URL for their IOCCC entry, or a 2nd URL such as a work or school or personal home page. For example, [Cody Boone Ferguson](authors.html#Cody_Boone_Ferguson) as of _Thu Nov 30 23:51:12 UTC 2023_ used: ``` "alt_url" : "https://ioccc.xexyl.net" ``` If the author wishes to not specify an alternate URL, or if the alternate URL is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "alt_url" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### deprecated_twitter_handle This _JSON member_ used to hold the twitter handle of the author. There **MUST** be one and only one `deprecated_twitter_handle` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. The IOCCC no longer is associated with twitter (or whatever someone chooses to call it), and so the `deprecated_twitter_handle` is **no longer used**. A _JSON value_ that is not a _JSON null_ is kept for only historic reasons. For example, Anthony C. Howe once used: ``` "deprecated_twitter_handle" : "@SirWumpus" ``` If the author wishes to not specify a twitter handle, or if the twitter handle is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "deprecated_twitter_handle" : null ``` Of course in the future we will not be asking for twitter handles so this means that unless the winner is a previous winner (before we moved to mastodon) this will always be `null` anyway. **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### mastodon ``` "mastodon" : "@mame@ruby.social" ``` This _JSON member_ holds the [Mastodon instance](https://en.wikipedia.org/wiki/Mastodon_(social_network)) handle of the author. There **MUST** be one and only one `mastodon` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. The _JSON string_ just be a valid Mastodon handle. In particular is must start with an at sign (_@_), followed by the Mastodon username, followed by a 2nd sign (_@_), followed by the Mastodon server instance used by the author. For more information in Mastodon, see the [Mastodon help](https://mastodon.help) guide. See the "Mastodon Address" section of that page in particular. The IOCCC Mastodon handle is: ``` @ioccc@fosstodon.org ``` The IOCCC uses Mastodon for announcements such as the opening and closing of a new IOCCC, changes to the IOCCC web site, updates during the judging process, and when new IOCCC entries are selected. We recommend you follow us on Mastodon. If the author wishes to not specify a Mastodon handle, or if the Mastodon handle is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "mastodon" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### mastodon_url ``` "mastodon_url" : "https://ruby.social/@mame" ``` This _JSON member_ holds the URL of the author's Mastodon page. There **MUST** be one and only one `mastodon_url` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. The _JSON string_ just be a valid URL. If the `mastodon` handle is a _JSON null_, them the `mastodon_url` **MUST** be a _JSON null_. If the `mastodon` handle is a _JSON string_, then the `mastodon_url` **MUST** be a _JSON string_. The `mastodon_url` is just a translation of the above mentioned Mastodon handle. For example, if the Mastodon handle is `@user@server.domain`, then the `mastodon_url` would be `https://server.domain/@user`. If the author wishes to not specify a Mastodon URL, or if the Mastodon URL is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "mastodon_url" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! See FAQ on "[Mastodon](#try_mastodon)" for more information on Mastodon. ##### github ``` "github" : "@mame" ``` This _JSON member_ holds the [GitHub](https://github.com) handle of the author. There **MUST** be one and only one `github` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. The `github` _JSON string_ **MUST** start with an at sign (_@_) and **MUST** be a valid GitHub username. The IOCCC uses GitHub to hold the [official winner repo of the IOCCC](https://github.com/ioccc-src/winner), and hosts [official IOCCC website](index.html) on GitHub pages. The IOCCC GitHub handle is [@ioccc-src](https://github.com/ioccc-src/). If the author wishes to not specify an GitHub handle, or if the GitHub handle is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "github" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### affiliation ``` "affiliation" : null ``` This _JSON member_ holds the affiliation of the author. There **MUST** be one and only one `affiliation` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_ or it **MUST** be a _JSON null_. An affiliation might be the name of a school, university, company, or organization. It is recommended that the affiliation _JSON string_ be the formal affiliation name. For example, the affiliation for the IOCCC would be: ``` "affiliation": "The International Obfuscated C Code Contest" ``` If the author wishes to not specify an affiliation, or if the affiliation is unknown, it should be the _JSON null_ as the _JSON value_ of this _JSON member_. For example: ``` "affiliation" : null ``` **NOTE**: The _JSON null_ is **NOT** enclosed in quotes! ##### winning_entry_set ##### entry_id ``` "winning_entry_set" : [ { "entry_id" : "2012_endoh1" }, { "entry_id" : "2012_endoh2" }, { "entry_id" : "2013_endoh1" }, { "entry_id" : "2013_endoh2" }, { "entry_id" : "2013_endoh3" }, { "entry_id" : "2013_endoh4" }, { "entry_id" : "2014_endoh1" }, { "entry_id" : "2014_endoh2" }, { "entry_id" : "2015_endoh1" }, { "entry_id" : "2015_endoh2" }, { "entry_id" : "2015_endoh3" }, { "entry_id" : "2015_endoh4" }, { "entry_id" : "2018_endoh1" }, { "entry_id" : "2018_endoh2" }, { "entry_id" : "2019_endoh" }, { "entry_id" : "2020_endoh1" }, { "entry_id" : "2020_endoh2" }, { "entry_id" : "2020_endoh3" } ] ``` (... as of Wed 23 Oct 2024 17:20:26 UTC.) The `winning_entry_set` _JSON member_ holds _JSON array_ containing one or more `entry_id` _JSON member_s. There **MUST** be one and only one `winning_entry_set` and the _JSON value_ **MUST** be a non-empty _JSON array_. Each value in that _JSON array_ **MUST** must contain a _JSON member_ whose _JSON name_ **MUST** be "_entry_id_" and those _JSON value_ is a valid entry ID. Due to the nature of the _So-called JSON spec_, the last value of the `winning_entry_set` _JSON array_ cannot end in a comma (_,_). See FAQ on "[author_handle.json](#author_json)" for information about entry ids. See FAQ on "[fixing author information](#fix_author)" for information about how to update and/or correct IOCCC author information. Jump to: [top](#)
### Q 3.7: How can I find my author handle?
If you are an _author_ of a winning _entry_, you may find your own _author_handle_ by going to your entry in the [authors.html](authors.html) web page and viewing the string that follows the _author_handle_: line. If you are not someone who has won a previous IOCCC, you will be able to select a potential _author_handle_ when you form your _submission_ tarball (see FAQ on "[how to enter the IOCCC](#enter)" ). **Helpful Hint**: If an _author_ clicks on their _author_handle:_ line link, you will be taken to that author's `author_handle.json` file. For example, [Brian Westley](authors.html#Brian_Westley) can view his author entry and see that his _author_handle_ is **Brian_Westley**. Clicking on the _author_handle_ shows the contents of the [Brian_Westley.json](%%REPO_URL%%/author/Brian_Westley.json) file. **IMPORTANT NOTE**: An `author` who has won a previous IOCCC is encouraged to reuse their `author_handle` so that new winning entries can be associated with the same author. See FAQ on "[fixing author information](#fix_author)" for information about how to update and/or correct IOCCC author information. See FAQ on "[author handle](#author_handle_faq)" for more information about author handles. See FAQ on "[author_handle.json](#author_json)" for information about the contents of these JSON file and how they are used. See FAQ on "[Author, Entry, Submission](#terms)" for more information on terms such as _author_, _entry_, and _submission_. Jump to: [top](#)
### Q 3.8: What is an `entry_id`?
An `entry_id` is a string that identifies a winning entry of the IOCCC. An `entry_id` is a 4-digit year, followed by an underscore, followed by a directory name. For example, the `entry_id` associated with Cody Boone Ferguson's 2nd winning IOCCC entry of 2020 is found under the directory [2020/ferguson2](2020/ferguson2/index.html). The `entry_id` for that winning entry is `2020_ferguson2`. Jump to: [top](#)
### Q 3.9: What is a `.entry.json` file and how is it used?
**TL:DR**: The contents of this JSON file contain information about each winning entry in JSON format. Each winning entry has a `.entry.json` file that includes data in JSON format about the entry. We describe the fields below in order to help you understand its contents. This file is created by the [cvt-submission.sh](bin/index.html#cvt-submission) tool as part of the final steps to announce a new set of winning IOCCC entries. Each winning entry has its own `.entry.json` filename of the form: `YYYY/winner/.entry.json` .. where _winner_ is the entry directory name, usually the name of the author. **IMPORTANT NOTE**: this file should **NOT** be manually modified! It is created by the [csv2entry](bin/index.html#csv2entry) tool when updating the manifest. #### `.entry.json` JSON file contents The syntax of a `.entry.json` follows the _So-called JSON spec_. See for information on the _So-called JSON spec_. A good way to understand the JSON file contents of a `.entry.json` file is to look at an example, for instance the [1984/laman/.entry.json](%%REPO_URL%%/1984/laman/.entry.json) file, as it is shorter than some of the others. As of _Fri 26 Jul 2024 17:29:15 UTC_, it contains: ``` { "no_comment" : "mandatory comment: because comments were removed from the original JSON spec", "entry_JSON_format_version" : "1.2 2024-09-25", "award" : "Third Place", "year" : 1984, "dir" : "laman", "entry_id" : "1984_laman", "title" : "1984.laman", "abstract" : "prints spiralling numbers laid out in columns", "author_set" : [ { "author_handle" : "Mike_Laman" } ], "manifest" : [ { "file_path" : "laman.c", "inventory_order" : 20, "OK_to_edit" : true, "display_as" : "c", "display_via_github" : true, "entry_text" : "entry source code" }, { "file_path" : "Makefile", "inventory_order" : 30, "OK_to_edit" : true, "display_as" : "makefile", "display_via_github" : true, "entry_text" : "entry Makefile" }, { "file_path" : "laman.orig.c", "inventory_order" : 50, "OK_to_edit" : false, "display_as" : "c", "display_via_github" : true, "entry_text" : "original source code" }, { "file_path" : "try.sh", "inventory_order" : 100, "OK_to_edit" : true, "display_as" : "shellscript", "display_via_github" : true, "entry_text" : "script to try entry" }, { "file_path" : "1984_laman.tar.bz2", "inventory_order" : 1415926535, "OK_to_edit" : false, "display_as" : "tbz2", "display_via_github" : false, "entry_text" : "download entry tarball" }, { "file_path" : ".entry.json", "inventory_order" : 4000000000, "OK_to_edit" : true, "display_as" : "json", "display_via_github" : true, "entry_text" : "entry summary and manifest in JSON" }, { "file_path" : ".gitignore", "inventory_order" : 4000000000, "OK_to_edit" : true, "display_as" : "gitignore", "display_via_github" : true, "entry_text" : "list of files that should not be committed under git" }, { "file_path" : ".path", "inventory_order" : 4000000000, "OK_to_edit" : false, "display_as" : "path", "display_via_github" : true, "entry_text" : "directory path from top level directory" }, { "file_path" : "README.md", "inventory_order" : 4000000000, "OK_to_edit" : true, "display_as" : "markdown", "display_via_github" : true, "entry_text" : "markdown source for this web page" }, { "file_path" : "index.html", "inventory_order" : 4294967295, "OK_to_edit" : false, "display_as" : "html", "display_via_github" : false, "entry_text" : "this web page" } ] } ```
##### Walk through of a `.entry.json` file
We now will walk through the above JSON document looking at all the JSON members: ##### `no_comment` ``` "no_comment" : "mandatory comment: because comments were removed from the original JSON spec" ``` Because the authors of the so-called JSON spec removed the ability to use comments in JSON (for reason(s) that seem to be less than credible), the IOCCC mandates this _JSON member_ be present in all IOCCC related JSON files. There **MUST** be one and only one `no_comment` _JSON member_ and the _JSON value_ **MUST** be the exact _JSON string_ as shown above. ##### `entry_JSON_format_version` ``` "entry_JSON_format_version" : "1.2 2024-09-25" ``` This _JSON member_ holds the format version of the `.entry.json` JSON file. There **MUST** be one and only one `entry_JSON_format_version` _JSON member_ and the _JSON value_ **MUST** be a _JSON string_. This is **NOT** the version of the contents! The `entry_JSON_format_version` would only changed when the overall format of the these files is modified: and then only those who maintain the [official IOCCC website](index.html) would be the one to do this in conjunction with changes to [bin directory tools](bin/index.html). ##### `award` ``` "award" : "Third Place" ``` This JSON string is the award title of the entry which the [Judges](judges.html) decide/decided when it becomes/became a winning entry. ##### `year` ``` "year" : 1984 ``` This JSON number is the year the contest ran, ended or was announced in. ##### `dir` ``` "dir" : "laman" ``` This JSON string is the subdirectory of the entry, **under** the year directory, in this case [1984](1984/index.html). With the above member, `year`, and this one, one can determine the directory of the entry, here being [1984/laman](1984/laman/index.html). ##### `entry_id` ``` "entry_id" : "1984_laman" ``` This is the ID of the entry in question and corresponds to the `entry_id` in the `author/author_handle.json` file. See FAQ on "[author handle](#author_handle_faq)" for more information about author handles. See FAQ on "[author_handle.json](#author_json)" for information about the contents of these JSON file and how they are used. ##### `title` The `title` for an entry's `.entry.json` file defaults to "`YYYY/dirname`". The `title` is not used at this time. For IOCCC winning entries after 2020, the `title` is obtained from the `.info.json` file with the entry was a submission. See the FAQ on "[.info.json](#info_json)" for more information on `.info.json` files. ##### `abstract` The `abstract` is a summary of the entry. The `abstract` is used as a head line in an entry's `index.html` file. For IOCCC winning entries after 2020, the `abstract` is obtained from the `.info.json` file with the entry was a submission. See the FAQ on "[.info.json](#info_json)" for more information on `.info.json` files. ##### `author_set` ``` "author_set" : [ { "author_handle" : "Mike_Laman" } ] ``` This JSON **array** has a list of `author_handle`s that indicate who won this entry. That _JSON member_ holds the author handle of the author. In most cases there is only one `author_handle` in a `.entry.json` file but in some there is more than one. See FAQ on "[author handle](#author_handle_faq)" for more information about an author handles. Normally the `author_handle` _JSON value_ should **NOT** be changed **unless there is a strong reason to do so**. If the _JSON value_ changes, then all of the `.entry.json` files for all of this author's winning IOCCC entries should also be changed. The `author_handle` _JSON value_ must match the basename (without the leading path and without the trailing `.json`) of the `author_handle.json` file. So a change of `author_handle` _JSON value_ would also require the `author_handle.json` file to also be renamed. The full name of an author may use non-ASCII characters so long as the full name is properly encoded as a _JSON string_. ##### `manifest` Finally there is the manifest JSON **array** that lists the files of the winning entry. Because each array member (a file) has the same fields we will only list one of the files in the manifest, providing comments about each field. After that we will list some files that are mandatory files, also with comments. There **MUST** be one and only one `manifest` _JSON member_ and the _JSON value_ **MUST** be a _JSON_ array. A shortened manifest for our example entry is: ``` "manifest" : [ { "file_path" : "laman.c", "inventory_order" : 20, "OK_to_edit" : true, "display_as" : "c", "display_via_github" : true, "entry_text" : "entry source code" } ] ``` Now we will describe each field of each file in the manifest: - `file_path` (string) * This _JSON_ **string** is the name of the file in question. - `inventory_order` (number) * This _JSON_ **number** decides which file list in the `index.html` file this file is listed and its order in that list. The details are beyond the scope of this document and it is only necessary to understand this if you are adding a file to the manifest. However as the [Judges](judges.html) are the ones who will be doing this this need not concern you. - `OK_to_edit` (boolean) * This _JSON_ **boolean** indicates whether this file should be modified, edited, replaced, or even removed directly. If `true` then a modification (i.e., edit) of the file, replacement of the file, or even removal os the file would be welcome via a pull request. See the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. If `false`, then the file almost certainlty should **NOT** be modified (i.e., edited), replaced or removed. Submitting a pull request that impacts such a `false` `OK_to_edit` file is likely to cause the pull request to be modifed or rejected. **IMPORTANT NOTE**: In most all cases, `OK_to_edit` should be set to `true`. There are only a few cases when `OK_to_edit` needs to be `false` that are documented below: * **Reason for `OK_to_edit == false` # 0**: The file is original source code file. Modifications of the **original source code** is only permitted it can be shown at the file is not the true **original source code**. See the FAQ on "[original source code](#orig_c)" for more information including how to open an [IOCCC issue](https://github.com/ioccc-src/winner/issues) if you believe the **original source code** is not a true original. * **Reason for `OK_to_edit == false` # 1**: The HTML file is generated by a [set of tools and scripts](bin/index.html)(including a related `Makefile` rule). Modifing HTML files that contain comments such as "_DO NOT MODIFY THIS FILE ..._" or "_Do not modify this web page ..._" will not have the desired effect because any modications will be overridden when the [set of tools and scripts](bin/index.html) (includeing a related `Makefile` rule). In order to properly change a generated HTML file, files such as a markdown file (often `README.md`) and/or sometimes JSON files (such as `.entry.json` or the `author/author_handle.json` JSON files) See the FAQ on "[fix website](#fix_website)" for information on submitting fixes to the IOCCC website. See the FAQ on "[update IOCCC author information](#fix_author)" for information how to modify `author/author_handle.json` JSON files. * **Reason for `OK_to_edit == false` # 2**: The file is a compressed tarball for an entry or set of entries for a given IOCCC year. Compressed tarball files are provided as a conveience for those who wish th download an IOCCC entry or all IOCCC entries for a given IOCCC year. These files are generate by [set of tools and scripts](bin/index.html)(including a related `Makefile` rules). Instead of trying to modify a compressed tarball, individual files that make up the compressed tarball should be modified instead. When you pull request to modify such individual files, the [IOCCC judges](judges.html) will run the appropriate [set of tools and scripts](bin/index.html) to update the compressed tarballs as needed. * **Reason for `OK_to_edit == false` # 3**: The file is a `.path` file. As the `.path` file is related to the path of the entry under an IOCCC year, this file should be consider as **read-only**. If you believe a `.path` file is in error, then please open up an [IOCCC issue](https://github.com/ioccc-src/winner/issues). See the FAQ on "[.path files](#dot_path)" for more information on `.path` files. See also the FAQ on "[fixing an entry](#fix_an_entry)" for information on opening up an IOCCC issue. * **Reason for `OK_to_edit == false` # 4**: There is some rare case or reason we forgot to document. The reasons previously listed for why the `OK_to_edit` set to `false` may be incomplete, or there is some special rare case. More likely, however, if some other file has `OK_to_edit` set to `false`, is a mistake. If you believe if `OK_to_edit` has the wrong value, please open a GitHub pull request. See the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. - `display_as` (string) * This _JSON_ **string** describes what kind of file it is and in particular how to **display** it. An entry source code file would be (all strings are lower case) `c`, a shell script would be `shellscript` and a `Makefile` would be `makefile`, for three examples of others. As updating the manifest is mostly a task for the [Judges](judges.html) you need not concern yourself with all the different names. - `display_via_github` (boolean) * This _JSON_ **boolean** indicates whether the file should be viewed at (that is linked to) GitHub or not. A good reason it might be viewed at GitHub is for syntax highlighting or if it should not be downloaded but would likely be downloaded by the browser otherwise. - `entry_text` (string) * This _JSON_ **string** is a short string that gives a summary of what the file is, for purposes of the file lists in the `index.html` inventory. Now that we have discussed the _JSON members_ of each file in the `manifest` we will give a list of **MANDATORY** files (for winning entry source code the names will depend on the year). - the entry source code * This file is typically called `winner.c`, where `winner` is as described above, or `prog.c` (for later years). The `entry_text` is always `"entry source code"`. - the entry Makefile * This is the submission's Makefile **modified** by the [Judges](judges.html), should the submission win. The `entry_text` is always `"entry Makefile"` and the `file_path` is **ALWAYS** `"Makefile"`. - the original source code file * This is the entry source code file that was submitted and that won. This will be named either `winner.orig.c` or `prog.orig.c`, depending on the year. This file may **NOT** be modified. The `entry_text` for this file is always `"original source code"`. See the FAQ on "[original source code](#original_source_code)" for more information. - the [entry tarball](#tarball) * This is the tarball of just the top level Makefile (and those included by it) and the entry itself, for convenience. It is named in the form of `YYYY_winner.tar.bz2`. For instance, for [1984/laman](1984/laman/index.html) it is called `1984_laman.tar.bz2`. This file is **NOT** displayed via GitHub. The `entry_text` is always `download entry tarball` as it is a file that is to be downloaded, should one wish to. - [.entry.json](#entry_json) file * This is the file we're currently discussing, the `.entry.json` file. The `entry_text` is always `"entry summary and manifest in JSON"` and the `file_path` is **ALWAYS** `".entry.json"`. - `.gitignore` * The list of files that should not be committed under git. Its `entry_text` is always `"list of files that should not be committed under git"` and the `file_path` is **ALWAYS** `".gitignore"`. - `.path` * This file contains the path to the entry subdirectory from the top level directory. For instance for [1984/laman](1984/laman/index.html) it is `"1984/laman"`. This file's `entry_text` is always `"directory path from top level directory"` and the `file_path` is **ALWAYS** `".path"`. - `README.md` * This file is the markdown source file for the `index.html` file. Its `entry_text` is always `"markdown source for this web page"` (because it is listed in `index.html`) and the `file_path` is **ALWAYS** `"README.md"` (renamed from the `remarks.md` provided in submissions). In most cases, if the entry has other html files then they are also formed from markdown files and the `entry_text` will be similar; the `file_path` in these cases will be the same as the html file except it will have the extension `.md`. - `index.html` * This is the main page of the entry, formed from the `README.md` file. Its `entry_text` is always `"this web page"` and its `file_path` is **ALWAYS** `"index.html"`. If the entry has an alternate source code file, often it will be in the form of `"winner.alt.c"` or `"prog.alt.c"`; this is also what the `file_path` will be. The `entry_text` will typically (not always but almost always) be `"alternate source code"`. Many entries have a script (or scripts) for the `Try` section in their index.html file. Usually this is called `try.sh` for the winning entry and `try.alt.sh` for the alternate source code (if there is an alternate version). Some, however, have another file name. The `entry_text` for the `try` scripts will be `script to try entry` or something along those lines. Jump to: [top](#)
### Q 3.10: How can I validate any JSON document?
If you want or need to verify that a JSON document (as a string or file) is valid, you can use the [jparse](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md) tool. The IOCCC version of the `jparse(1)` tool may be installed from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). The [FAQ.md file in the mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#download) contains information about how to find and compile the mkiocccentry toolkit, which includes the IOCCC version of the `jparse(1)` tool, located under the `mkiocccentry` directory as `jparse/jparse`. Additionally you may install the `jparse(1)` tool from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry): ``` git clone https://github.com/ioccc-src/mkiocccentry.git cd mkiocccentry && make clobber all" 1>&2 cd jparse && sudo make install clobber" 1>&2 ``` The syntax of `jparse(1)` is very simple: ``` jparse foo.json ``` If the tool exits 0 then the document is valid JSON; otherwise it'll show an error message. If you want to see more information about the parsing you can increase the verbosity with the `-v` option. For instance: ``` jparse -v 3 foo.json ``` If the tool is not installed then you will obviously have to specify the path of the tool. **NOTE**: the `jparse` subdirectory is a clone of the official [jparse repo](https://github.com/xexyl/jparse/issues) but we recommend you compile and install via the `mkiocccentry` repo because it has the dependencies built in, and because the `mkiocccentry` copy is that which is used by the current IOCCC, as the two can sometimes be different. Jump to: [top](#)
## Section 4: Compiling IOCCC entries
Jump to: [top](#)
### Q 4.0: What Makefile rules are available to build or clean up IOCCC entries?
In general the best way to compile everything in an entry directory is to run: ``` make clobber all ``` If you wish to compile every entry for every year you should go to the top level directory and run the same command as above, `make clobber all`. The `all` rule will build everything necessary except for the alternate versions. Every Makefile has an `alt` rule but it will only do something if an alternate version exists. To build all the entries along with any alternate code you can do from the top level directory: ``` make clobber everything ``` If you wish to only build alternate code you can do: ``` make clobber alt ``` If you wish to not remove the entry binaries and only compile the additional alt versions: ``` make alt ``` The following Makefile rules should be in all Makefiles: - `all`: build the entry programs (main program and any supplementary program) - `alt`: build alternate code - `clobber`: clean up object files and all binary files (except for those that are not compiled) - `clean`: a simpler version of `clobber` that only removes object files. `make clobber` depends on `clean` so running `make clobber` will invoke `make clean`. - `everything`: equivalent to `make all alt`. Are there any other rules? You tell us! The top level and the year (e.g. `1984/Makefile`, `1985/Makefile` etc.) `Makefile`s recurse into the subdirectories for each entry so you can compile individual entries, entries of a given year or all entries, based on what you wish to do. NOTE about the above rules: the Makefile default assumes `cc` which might be a gcc-based compiler, or a clang-based compiler, or some other compiler. Only by forcing `CC=clang` or `CC=gcc` will one invoke a specific compiler to, say, enable or disable additional warnings or flags. Even so different versions or compilers might do different things, have different defects or other issues. Note that the `Makefile`s check the `CC` variable by substrings so that if you were to do something like `make CC=gcc=mp-12` it would register as `gcc`. Jump to: [top](#)
### Q 4.1: What form of make(1) is supported by IOCCC?
For the [IOCCC](index.html) [mkiocccentry submission toolkit](https://github.com/ioccc-src/mkiocccentry) and the [winning IOCCC entries](years.html) we support *ONLY* GNU Makefile syntax. This means that if you only have Cygwin or a BSD `make(1)` (often `bmake(1)`) or some other `make(1)` utility the Makefiles we use will not be compatible. We do not intend on supporting anything but the GNU `make(1)` utility so if you do not currently have it installed you will have to do that in order to compile entries for the IOCCC. If you are submitting an entry this will also be necessary. If you do not have GNU `make(1)` you might look for `gmake` as that is what it often is packaged as. Then you can use `gmake` instead. For instance if you go to the top level directory of the winner repo you can do: ``` gmake ``` In the case that the Makefile uses the `MAKE` variable you will have to override it like: ``` gmake MAKE=gmake ``` though of course for both you may specify a rule or rules to run. Jump to: [top](#)
## Section 5: Dependencies for some IOCCC entries
Jump to: [top](#)
### Q 5.0: How do I compile and run an IOCCC entry that requires X11?
#### Generally, to compile and run an IOCCC entry that requires X11:
You must have the X11 related include files and X11 libraries in order to compile the IOCCC entry. In order to do this you will need to install Xorg and related packages including development related packages. If you have macOS see further down for different instructions. Otherwise: in particular you must: * Install the Xorg server. * Configure the Xorg server for your graphics environment. * Install a X11 terminal application. * Start the Xorg server. * Launch the X11 terminal application. * Run the IOCCC entry in the X11 terminal application. By X11 terminal application we suggest one of: * [Gnome](https://www.gnome.org) terminal application * [KDE](https://kde.org) terminal application * `xterm(1)` terminal application See below for various system related hints that may be of help.
#### X.org server has been deprecated
The Red Hat RHEL9.0 release notes state that [X.org Server is now deprecated](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/9.0_release_notes/deprecated_functionality#deprecated-functionality_graphics-infrastructures). According to this [Linux for Devices tutorial on XOrg](https://www.linuxfordevices.com/tutorials/linux/install-xorg-on-linux) as of 2023 Mar 25 (quote verbatim): > Recently, RHEL developers categorized Xorg [Xorg was put in the ‘deprecated’ software](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/9.0_release_notes/deprecated_functionality), as its development has mostly halted. Subsequent updates will completely replace it with Wayland, a more modern windowing system.. Although Wayland is not fully developed yet, many applications do not support it properly yet and screen sharing might not work sometime, but it is the future. Fedora, also developed by RHEL, has switched to a Wayland session as it’s default windowing system (And it works flawlessly on my Laptop). See the [Wayland](https://wayland.freedesktop.org) website for more details. **IMPORTANT NOTE**: We do **NOT** know if IOCCC entries will run under **Wayland**. Some IOCCC entries that use X11 might be OK while other IOCCC entries that use X11 in an unusual way might fail under **Wayland**. See the [Wayland FAQ](https://wayland.freedesktop.org/faq.html) for more information. If your system uses **Wayland** and not X11, you might give the IOCCC entries that use X11 a try. They might work but again we do not know. **IMPORTANT NOTE**: The [IOCCC judges](judges.html) **do not support IOCCC entries**. See the FAQ on "[no entry support](#no_support)". So if an IOCCC entry that uses X11 fails under **Wayland**, and you wish to provide a fix to the IOCCC entry so that it will run under **Wayland**, then consider submitting a fix so that it will run under **Wayland**. See the FAQ on "[fixing an entry](#fix_an_entry)" for more information. Basically: if you discover an entry does not work in Wayland you are welcome to provide **alternate code** that works for Wayland. We will happily credit you in the [thanks-for-help.html](thanks-for-help.html) file. #### Red Hat based Linux First, see the FAQ on "[general X11](#X11_general)". Install Xorg and related packages: ``` sudo dnf install --skip-broken --best --exclude xorgxrdp \ --exclude xorgxrdp-glamor '*xorg*' 'libx*' 'libX*' 'fontconfig*' ``` See also: * [How to Configure X11 in Linux](https://www.wikihow.com/Configure-X11-in-Linux) **IMPORTANT NOTE**: The X.org server has been deprecated. See the FAQ on "[X.org deprecated](#Xorg_deprecated)" for more information. #### macOS First, see the FAQ on "[general X11](#X11_general)". However, for macOS, instead of installing the Xorg server, you need to install and launch the [most recent XQuartz](https://www.xquartz.org) application and then run the IOCCC entry from the [Xterm window shell](https://en.wikipedia.org/wiki/Xterm). As an example we will use [1993/jonth](1993/jonth/index.html) which works with macOS 14.2.1 (macOS Sonoma). First of all you will need to install the [most recent XQuartz](https://www.xquartz.org), preferably on an [Apple supported version of macOS, preferably the most recent version](https://support.apple.com/macOS). After it is installed, open the "XQuartz" application (usually located in `/Applications/Utilities/XQuartz.app`) by typing at the command line: ``` open /Applications/Utilities/XQuartz.app ``` With the "XQuartz" application open you will get an [X Window System Manager](https://www.x.org/wiki/) launched with an [Xterm window shell](https://en.wikipedia.org/wiki/Xterm) started: xterm-launch in macOS At this point you need to cd to the winning directory and compile it. For example: compiling an entry in xterm in macOS And then run the program as directed by the `index.html` file. For example with `1993/jonth`: running 1993/jonth in macOS Note that you can compile the code in your regular terminal prior to opening XQuartz, should you wish to. You can even run it from that terminal and it should open XQuartz. **IMPORTANT NOTE**: The X.org server has been deprecated. See the FAQ on "[X.org deprecated](#Xorg_deprecated)" for more information. #### Debian based Linux First, see the FAQ on "[general X11](#X11_general)". According to the [Debian Xorg wiki](https://wiki.debian.org/Xorg), installing X11 requires: ``` sudo apt install xorg ``` **IMPORTANT NOTE**: The X.org server has been deprecated. See the FAQ on "[X.org deprecated](#Xorg_deprecated)" for more information. #### Other Linux distributions First, see the FAQ on "[general X11](#X11_general)". For general documentation on installing X11, this [ServerGUI for Ubuntu](https://help.ubuntu.com/community/ServerGUI), and in particular, these may be helpful: * [X11 Client Installation](https://help.ubuntu.com/community/ServerGUI#X11_Client_Installation) * [X11 Server Installation](https://help.ubuntu.com/community/ServerGUI#X11_Server_Installation) * [Full Desktop Environments](https://help.ubuntu.com/community/ServerGUI#Full_Desktop_Environments) See also: * [How to Configure X11 in Linux](https://www.wikihow.com/Configure-X11-in-Linux) For systems that have the `dnf(1)` command: ``` sudo dnf install --skip-broken --best --exclude xorgxrdp \ --exclude xorgxrdp-glamor '*xorg*' 'libx*' 'libX*' 'fontconfig*' ``` For systems that have the `yum(1)` command: ``` sudo yum install --skip-broken --best --exclude xorgxrdp\ --exclude xorgxrdp-glamor '*xorg*' 'libx*' 'libX*' 'fontconfig*' ``` **IMPORTANT NOTE**: The X.org server has been deprecated. See the FAQ on "[X.org deprecated](#Xorg_deprecated)" for more information. #### Package website First, see the FAQ on "[general X11](#X11_general)". See the [X.org](https://x.org/wiki/) foundation website. **IMPORTANT NOTE**: The X.org server has been deprecated. See the FAQ on "[X.org deprecated](#Xorg_deprecated)" for more information. Jump to: [top](#)
### Q 5.1: How do I compile and install SDL1 or SDL2 for entries that require it?
This depends on your operating system but below are instructions for Linux and macOS with alternative methods for macOS and different package managers with Linux. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install SDL2 SDL2-devel sdl12-compat sdl12-compat-devel ``` Older RHEL distributions might have to use "yum" instead of "dnf" in the above command. In the past it was said that one might need to run `make` like: ``` make ... SDL2_INCLUDE_ROOT=/usr ``` or set the following environment variable: ``` export SDL2_INCLUDE_ROOT=/usr ``` but this might not be necessary in more modern days especially as we use `sdl-config` and `sdl2-config` which should find the proper paths.
#### macOS
If you're using macOS there are at least three ways to obtain it. You can use Homebrew or MacPorts. If you do not wish to use either of those package managers, you can always try to install via the package website. For macOS we do recommend using Homebrew or MacPorts instead of using the package website. ##### macOS via Homebrew If you have not already done so, install [Homebrew](https://brew.sh). Then to install SDL and SDL2, execute the following command: ``` brew install sdl2 sdl12-compat eval "$(opt/homebrew/bin/brew shellenv)" ``` ##### macOS via MacPorts If you haven't already, install [MacPorts](https://www.macports.org/install.php). Then run: ``` sudo port install libsdl libsdl2 ``` #### Debian based Linux Execute the following as root or via sudo: ``` apt install libsdl1.2debian libsdl1.2-dev libsdl2-dev ``` and then try `make all` again. In the past it was said that one might need to run `make` like: ``` make ... SDL2_INCLUDE_ROOT=/usr ``` or set the following environment variable: ``` export SDL2_INCLUDE_ROOT=/usr ``` but this might not be necessary in more modern days especially as we use `sdl-config` and `sdl2-config` which should find the proper paths. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [SDL website](https://www.libsdl.org) and follow their instructions for downloading, installing and using SDL. We recommend trying a method suitable for your environment first, if possible. #### NOTE: there might be extra SDL packages required In the case that some entries do not work even with SDL1/SDL2 installed it might be that you need additional SDL libraries. See the entry's index.html for details. If something is not noted you're welcome to report it as an issue or fix it and make a pull request. See the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. Jump to: [top](#)
### Q 5.2: How do I compile and install ncurses for entries that require it?
This depends on your operating system but below are instructions for Linux and macOS with alternative methods for macOS and different package managers with Linux. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install ncurses ncurses-devel ``` #### macOS With macOS it should already be installed. If it is not you might have to do: ``` xcode-select --install ``` and agree to the terms and conditions and proceed with the install. ##### macOS via Homebrew Not applicable, see above. ##### macOS via MacPorts Not applicable, see above. #### Debian based Linux Execute the following as root or via sudo: ``` apt install libncurses6 ``` and then try `make all` again. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### NetBSD Uses of the NetBSD distribution should install and use the [ncurses package for NetBSD](https://cdn.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/ncurses/README.html). #### Package website Go to the [ncurses website](https://invisible-island.net/ncurses/) and follow their instructions for downloading, installing and using ncurses. We recommend trying a method suitable for your environment first, if possible. #### See also See the FAQ on "[curses](#curses)" for more information on curses vs ncurses. Jump to: [top](#)
### Q 5.3: How do I compile and run an IOCCC entry that requires sound?
This might depend on the entry but most likely the Swiss Army Knife of sound processing programs, [SoX](https://sox.sourceforge.net), will work. How to install depends on your OS. See below. After it is installed, you should be able to compile and use the program as described in the index.html file. #### Red Hat based Linux As root or via sudo: ``` dnf install -y sox sox-devel ``` #### macOS For macOS there are two well known options. ##### macOS via Homebrew If you have not already done so, install [Homebrew](https://brew.sh). Then to install SoX, execute the following command: ``` brew install sox eval "$(opt/homebrew/bin/brew shellenv)" ``` ##### macOS via MacPorts If you haven't already, install [MacPorts](https://www.macports.org/install.php). Then run: ``` sudo port install sox ``` #### Debian based Linux Usually the index.html file will explain how to use it under Debian so we do not include this here, at least for now. #### Package website Not applicable, see above. #### Other Linux distributions Usually the index.html file will explain how to use it under Linux so we do not include this here, at least for now. Jump to: [top](#)
### Q 5.4: How do I compile and install tcpserver for entries that require it?
If your OS package manager does not have the package `tcpserver` you can download, making sure you're in a temporary directory, and compile the source like: ``` wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz tar ucspi-tcp-0.88.tar.gz cd ucspi-tcp-0.88 make ``` Then as root or via `sudo(1)` enter: ``` make setup check ``` That will install it to `/usr/local/bin`. Now you should be able to use the entry in question. Jump to: [top](#)
### Q 5.5: How do I compile and install netpbm for entries that require it?
This depends on your operating system for which we describe a couple below. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install netpbm-progs netpbm ``` Older RHEL distributions might have to use "yum" instead of "dnf" in the above command. #### macOS If you're using macOS there are at least three ways to obtain it. You can use Homebrew or MacPorts. If you do not wish to use either of those package managers, you can always try to install via the package website. For macOS we do recommend using Homebrew or MacPorts instead of using the package website. ##### macOS via Homebrew If you have not already done so, install [Homebrew](https://brew.sh). Then to install netpbm, execute the following command: ``` brew install netpbm ``` ##### macOS via MacPorts If you haven't already, install [MacPorts](https://www.macports.org/install.php). Then run: ``` sudo port install libnetpbm netpbm ``` #### Debian based Linux Execute the following as root or via sudo: ``` apt install netpbm ``` and then try `make all` again. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [netpbm website](https://netpbm.sourceforge.net) and follow their instructions for downloading, installing and using netpbm. We recommend trying a method suitable for your environment first, if possible. Jump to: [top](#)
### Q 5.6: How do I compile and install libjpeg-turbo for entries that require it?
This depends on your operating system for which we describe a couple below. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install libjpeg-turbo-utils libjpeg-turbo-devel libjpeg-turbo ``` Older RHEL distributions might have to use "yum" instead of "dnf" in the above command. #### macOS If you're using macOS there are at least three ways to obtain it. You can use Homebrew or MacPorts. If you do not wish to use either of those package managers, you can always try to install via the package website. For macOS we do recommend using Homebrew or MacPorts instead of using the package website. ##### macOS via Homebrew If you have not already done so, install [Homebrew](https://brew.sh). Then to install libjpeg-turbo, execute the following command: ``` brew install libjpeg-turbo ``` ##### macOS via MacPorts If you haven't already, install [MacPorts](https://www.macports.org/install.php). Then run: ``` sudo port install libjpeg-turbo libjpeg-turbo-devel ``` #### Debian based Linux Execute the following as root or via sudo: ``` apt install libturbojpeg0 libturbojpeg0-dev ``` and then try `make all` again. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [libjpeg-turbo website](https://www.libjpeg-turbo.org) and follow their instructions for downloading, installing and using libjpeg-turbo. We recommend trying a method suitable for your environment first, if possible. Jump to: [top](#)
### Q 5.7: How do I compile and install ImageMagick for entries that require it?
This depends on your operating system for which we describe a couple below. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install ImageMagick ``` Older RHEL distributions might have to use "yum" instead of "dnf" in the above command. #### macOS If you're using macOS there are at least three ways to obtain it. You can use Homebrew or MacPorts. If you do not wish to use either of those package managers, you can always try to install via the package website. For macOS we do recommend using Homebrew or MacPorts instead of using the package website. ##### macOS via Homebrew If you have not already done so, install [Homebrew](https://brew.sh). Then to install ImageMagick, execute the following command: ``` brew install ImageMagick ``` ##### macOS via MacPorts If you haven't already, install [MacPorts](https://www.macports.org/install.php). Then run: ``` sudo port install ImageMagick ``` #### Debian based Linux Execute the following as root or via sudo: ``` apt install imagemagick ``` and then try `make all` again. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [ImageMagick website](https://imagemagick.org) and follow their instructions for downloading, installing and using ImageMagick. We recommend trying a method suitable for your environment first, if possible. Jump to: [top](#)
### Q 5.8: How do I compile and install OpenGL for entries that require it?
This depends on your operating system for which we describe a couple below. In general OpenGL needs X11 to be installed and the X Window Server to be running. See the FAQ on "[X11](#X11)" for general information about X11. Once X11 is install and the X Window Server is running, one needs to compile and link with the two libraries, _GL_ and _GLU_, which the Makefile should do if you just run `make`. **NOTE**: The OpenGL development effort is being managed by [vulkan.org](https://vulkan.org). We suggest you check out their resource for further information on OpenGL. #### Red Hat based Linux Execute the following as root or via sudo: ``` sudo dnf install glew-devel SDL2-devel SDL2_image-devel glm-devel freetype-devel ``` See [OpenGL Programming/Installation/Linux](https://web.archive.org/web/20240413102531/https://en.wikibooks.org/wiki/OpenGL_Programming/Installation/Linux) for details. Older RHEL distributions might have to use "yum" instead of "dnf" in the above command. #### macOS In the past, macOS has come with OpenGL pre-installed. However as of macOS 10.14, [OpenGL has been deprecated on macOS](https://developer.apple.com/library/archive/documentation/GraphicsImaging/Conceptual/OpenGL-MacProgGuide/opengl_intro/opengl_intro.html) (in favor of Metal). As long as Apple continues to ship OpenGL pre-installed and it works, you should be good to go. However if Apple drops support for OpenGL later on, you might look to install OpenGL via Homebrew or MacPorts. With Homebrew: ``` brew install glfw3 glew ``` might help. On the other hand, with MacPorts: ``` sudo port install glfw glfw-devel glew ``` might help. #### Debian based Linux Execute the following as root or via sudo: ``` sudo apt-get install libglew-dev libsdl2-dev libsdl2-image-dev libglm-dev libfreetype6-dev ``` and then try `make all` again. See [OpenGL Programming/Installation/Linux](https://en.wikibooks.org/wiki/OpenGL_Programming/Installation/Linux) for details. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [Vulkan website](https://vulkan.org) and follow their instructions for downloading, installing and using OpenGL. We recommend trying a method suitable for your environment first, if possible. Jump to: [top](#)
### Q 5.9: How do I compile and install zlib for IOCCC entries that require it?
This depends on your operating system but below are instructions for Linux and macOS with alternative methods for macOS and different package managers with Linux. #### Red Hat based Linux Execute the following as root or via sudo: ``` dnf install zlib ``` #### macOS With macOS it should already be installed. If it is not you might have to do: ``` xcode-select --install ``` and agree to the terms and conditions and proceed with the install. ##### macOS via Homebrew Not applicable, see above. ##### macOS via MacPorts Not applicable, see above. #### Debian based Linux Execute the following as root or via sudo: ``` apt install zlib1g zlib1g-dev ``` and then try `make all` again. #### Other Linux distributions Use your package manager to install the appropriate packages. Try the search feature of the package manager to determine which packages you need to install. Note that you might have to install both the library and the developmental packages: one for compiling and one for linking / running. #### Package website Go to the [zlib website](https://www.zlib.net) and follow their instructions for downloading, installing and using zlib. We recommend trying a method suitable for your environment first, if possible. Jump to: [top](#)
### Q 5.10: How do I install Ruby for entries that require it?
Please see the [official Ruby installation guide](https://www.ruby-lang.org/en/documentation/installation/). Jump to: [top](#)
### Q 5.11: How do I install rake for entries that require it?
First, if `gem` is not installed, see the [gem GitHub repo ](https://github.com/rubygems/rubygems). Assuming you have `git(1)` installed, you can do: ``` git clone https://github.com/rubygems/rubygems cd rubygems && exe/gem install rake ``` Otherwise, you can download the zip file, extract it, cd to the directory and then run: ``` exe/gem install rake ``` Once this is done, try as root or via `sudo`: ``` gem install rake ``` Jump to: [top](#)
### Q 5.12: How do I compile entries that use ncurses if we only have the old classic curses?
Entries such as these were written to compile using the **ncurses** package: * [2004/arachnid](2004/arachnid/index.html) * [2006/night](2006/night/index.html) * [2014/skeggs](2014/skeggs/index.html) * [2020/endoh1](2020/endoh1/index.html) * etc. #### Installing ncurses If your system does not have **ncurses** installed, check with your system provider for a package. In some cases you may need to also install a "development" variant (such as `ncurses-devel`) in addition to the main package to install the `ncurses.h` include file. You may also install from the [official ncurses site](https://invisible-island.net/ncurses/). #### Pretending to use classic curses If you do not wish to, or cannot install the **ncurses** package for your system, and you have the **old classic curses** instead, you may try hacking the code to and use the **old classic curses** package. You will need to modify the `Makefile` and/or `prog.c` to include `curses.h` instead of `ncurses.h` and to link to `-lcurses` instead of `-lncurses`. You may also need to change use of `acs_map` to use `_acs_map`, for example. For example, this [unused pull request](https://github.com/ioccc-src/winner/pull/144/files) shows how one may modify the [2004/arachnid](2004/arachnid/index.html) entry to use the **old classic curses** package. Be aware that **old classic curses** is not fully compatible with the **ncurses**. Resizing the terminal window, for example, may lead to complications. A more reliable approach to install **ncurses** instead. See the FAQ on "[ncurses](#ncurses)" for more information installing **ncurses**. Jump to: [top](#)
## Section 6: Problems compiling IOCCC entries
Jump to: [top](#)
### Q 6.0: Why don't certain IOCCC entries compile?
Some entries that won the IOCCC, particularly entries from long ago, might not compile on more modern systems because the C language has evolved (i.e. the modern C compilers are much more strict in what they accept as a valid program), or the entry depended on operation system and library features that where common back then but are different/missing today. In some cases the American National Standards Institute's ANSI C committee has damaged the C standard to the point where perfectly valid C programs no longer compile with modern compilers. As such some old IOCCC entries can no longer be compiled with modern compilers (though a great deal of these were fixed in 2023). In other cases, it might be your compiler. For instance `clang` is very strict on some things that `gcc` is perfectly fine with. A great deal of these have been fixed but it is possible that some do not work. In particular, some entries do require a certain compiler, or they might not work with certain compilers or a certain architecture. Some entries generate C code and some of that generated code will not compile with certain compilers, usually `clang`. Please see the other FAQs in this section as they might offer helpful hints, especially in cases where something else needs to be installed. Please see the [bugs.html](bugs.html) file for details about known problems with IOCCC entries. In some cases you may be dealing with a problematic entry. In a few fun cases, the IOCCC does not compile by design! If you have a fix that makes a minimal impact to the entry, then please consider submitting that change in the form of a pull request. Please see FAQ on "[fixing an entry](#fix_an_entry)". See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. In some cases alternative code has been added that does compile on some or most systems. Check the write up for the entry for "alt" code and possible ways to compile and run that code. In some cases we replaced the original code (but not the `.orig.c` file!) with code that works for modern systems but one can view the original code in the `.orig.c` files (sometimes the original code is also in the directory as a `dirname.alt.c` or `prog.alt.c`). See the FAQ on "[original source code](#original_source_code)" for more information. Jump to: [top](#)
#### Q 6.1.1: Why do some IOCCC entries fail to compile and/or run under macOS?
If the entry requires gcc and you did not explicitly install gcc in macOS you will not be able to run or use these entries. This is because macOS gcc is actually clang, even `/usr/bin/gcc`. That being said many (if not most) of these entries have been fixed. In some cases the [bugs.html](bugs.html) file may note a known macOS problem with an entry. Should you manage to port the entry, and assuming your changes also attempt to preserve the original intent of the IOCCC entry, we would encourage you to submit a pull request with your ported code. Please see the FAQ on "[fixing an entry](#fix_an_entry)" for details. Jump to: [top](#)
### Q 6.2: Why do Makefiles use -Weverything with clang?
While we know that use of `-Weverything` is generally not recommended by `clang` C compiler developers, we do use the `-Weverything` option in a certain case in IOCCC entry `Makefile`s. The use of `-Weverything` is limited to when one forces `CC=clang` or more generally if the string 'clang' is in `$(CC)`. If `$(CC)` contains 'gcc' the 'gcc' specific options are run instead. Users with clang compilers are not required to set `CC=clang` or equivalent but when they do, `-Weverything` is enabled with all of its challenges, pedantic warnings, and sometimes warnings about things that do not matter, some of which are frankly frivolous and often downright dubious. To enable this feature: ``` make clobber all CC=clang ``` IOCCC authors who have access to `clang` might wish to try their hand at compiling with `-Weverything` while using a minimum of `-Wno-foo` statements. Sometimes there is a technical or pedantic issue that `-Weverything` warns about that would merit a change to your C code; often, however, it is not even possible to fix let alone is it worth it. Of course if you're running out of bytes due to rule 2[ab] one might not have much choice. This is something that obfuscation authors simply sometimes have to deal with! If you try to minimize the number of `-Wno-foo` options needed with `-Weverything`, please mention this in your remarks about the entry, as the judges note you attempt to honor it (see also below). In some cases your obfuscated code will issue warnings with `-Weverything` no matter what: the `-Wno-poison-system-directories` is a common example of this but there are others as well, sometimes depending on the version of `clang`. If you do try for a compile with `clang -Weverything`, keep on mind that while _your_ compile environment might be warning free, a different clang version or a different build environment might still have warnings. For instance the warning set is different in macOS (which by default is `clang`: even when run as `gcc`!) than Linux (due to versions and possibly other things)! Given that your entry **MUST** work as documented, you may be safer to say that your entry keeps the number of warnings and `-Wno-foo` options while compiling with `clang -Weverything` at a minimum. You might want to say the version number and platform (OS and OS version) too as an extra safety net. Because if you claim zero warnings, and we find a warning situation, this may diminish the value of your entry as it is not as documented. Thus it might be wise to point this out and if you can test it in multiple platforms (or versions of `clang`, see below note) this would be advisable. **NOTE**: different versions of `clang` have other differences as well. For instance a defect of `clang` that required numerous entries to be fixed for clang is that it requires that `main()`'s arguments to be of a specific type. However some versions of `clang` are more strict in the number of args allowed. Jump to: [top](#)
## Section 7: Running IOCCC entries
Jump to: [top](#)
### Q 7.0: What are `try.sh` and `try.alt.sh` scripts and why should I use them?
A lot of the entries, old and otherwise, have complicated uses and/or have numerous uses, and having a script that automates these for viewers improves the usability of these entries so one can enjoy them better. The `try.sh` script is for the original entry and the `try.alt.sh` script is for alternate versions. These scripts are usually for the `Try:` and `Alternate try:` sections in the `index.html` files. Some entries provide additional scripts that are meant to run the entry as well but might not fit in the `try` model though some are used by a `try.sh` / `try.alt.sh` script. Although you're certainly welcome to copy and paste or type the commands in manually, sometimes the scripts will do additional things that you might miss and there are some other benefits as well which you would miss if you did not use them. Nevertheless, if you prefer to do it manually, whether to help you process or appreciate the entry more, then please do so. Jump to: [top](#)
### Q 7.1: An IOCCC entry messed up my terminal application, how do I fix this?
The simplest way to do this is to type `reset`. If echo was disabled you can get usually away with `stty echo`. Sometimes you can also get away with `stty sane`. `reset` does the most but note that it will clear the screen; it is not the clearing of the screen, however, that solves the problem, so `clear` will not help. Jump to: [top](#)
### Q 7.2: Why does an IOCCC entry fail to compile and/or run?
What may have worked years ago may not work well or work at all today. Please note that the IOCCC judges do **NOT** support IOCCC entries. Nevertheless, there may be a number of reasons why an IOCCC entry may fail to run well if it can run at all. In some cases programs that may have worked on an old computer system longer work on modern computers. Some IOCCC entries do not work well, or no longer work on modern computers or modern operating systems, though again a great deal of these were fixed for modern systems. There are some cases where certain compilers or even certain versions are necessary for the program to function in part or even completely. Some IOCCC entries might need operating system services that might not be present on your system, as well. In some cases the IOCCC entry simply has [bugs or (Mis)features](bugs.html). If you are having problems compiling or running an IOCCC entry, we recommend that you look in [bugs.html](bugs.html) to see if there is a known bugs or (Mis)feature. In some cases what you may think is a bug is actually a feature that was intentionally written by the author(s). In some cases the problem is well known and we are looking for someone to attempt to fix it. In some cases there is an alternate version of the IOCCC entry that you may wish to try. It's also possible that you have discovered a bug in a winning IOCCC entry. If so, you are invited to try and fix the IOCCC entry and submit that fix by way of a [GitHub pull request](https://github.com/ioccc-src/winner/pulls). Please see the FAQ on "[fixing an entry](#fix_an_entry)" for how to submit a fix to an IOCCC entry. Jump to: [top](#)
### Q 7.2.1: Why does an IOCCC entry fail to compile and/or run run on my 64-bit system?
Unfortunately some older entries are non-portable and require 32-bit support or 32-bit binaries. A problem system here is that as of macOS Catalina (10.15) macOS no longer supports 32-bit binaries. If the entry acts on a certain type of binary, say ELF, then that will also be a problem depending on the entry. For example [2001/anonymous](2001/anonymous/index.html) requires 32-bit ELF binaries. There are a few example entries that require 32-bit binaries. We have tried to note these in both the respective Makefiles and index.html files but it is possible that some were missed. These entries are very likely in the [bugs.html](bugs.html) file and we welcome any help in making an alternate version for 64-bit systems. Many were fixed to work with modern systems but some are supposed to only work with 32-bit systems so any updated version of these entries should be an alternate version. Other entries like [2001/herrmann2](thanks-for-help.html#2001_herrmann2) now work with 32-bit AND 64-bit systems. Please see the [bugs.html](bugs.html) file for the problematic entry in question to see if the problem is known, and if a fix is wanted, consider trying to port the code to a 64-bit system and submitting a pull request with that change. Pull requests that fix such code while trying to minimize the impact of any changes and preserving the spirit of the original code are very welcome! Please see the FAQ on "[fixing an entry](#fix_an_entry)" for details. See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. Jump to: [top](#)
### Q 7.3: How do I find out how to send interrupt/EOF etc. for entries that require it?
For some entries one needs to send interrupt or EOF or some other signal/other special characters. There are typical defaults like (where `^` = ctrl): - `^D` for EOF (`eof`) - `^C` for interrupt (`intr`) - `^U` for kill (`kill`) and various others. But if you don't know this you can find out through the `stty(1)` command with the `-a` option. For instance with macOS you might see: ``` $ stty -a speed 9600 baud; rows 40; columns 155; intr = ^C; quit = ^\; erase = ^?; kill = ^U; eof = ^D; [..snip..] ``` If you know the name you can use `grep` to find the correct line and if your implementation of `grep(1)` has the `-o` option you can filter it. For instance to find what the `intr` is set to: ``` $ stty -a |grep -o 'intr = ^[[:alpha:]]' intr = ^C ``` ... assuming of course that it's a ctrl combination :-) If for some strange reason it's not you might have to do something else including just piping it to just `grep intr` or whatever. Jump to: [top](#)
### Q 7.4: How do I download individual winning entries or all winning entries of a given year?
Although one can clone the entire [winner repo](https://github.com/ioccc-src/winner) to get the entire website and all entries, we also provide, as a convenience, a way to download individual entries as well as a way to download a year's winning entries. Please note that some of the links in the html files will not work! This is because you are not downloading the full website. If you want to view the entry with links intact you should clone the repo or view it on the [official IOCCC website](index.html) instead. #### Individual winning entry tarballs The individual entry tarballs are named in the form of `YYYY/winner/YYYY_winner.tar.bz2` (e.g. [1984/mullender/1984_mullender.tar.bz2](1984/mullender/1984_mullender.tar.bz2)) and they contain a single entry as well as some additional necessary files. Each entry tarball is linked to in its `index.html` (e.g. [1984/mullender/index.html](1984/mullender/index.html)) manifest, listed in the _Secondary files_ list. These tarballs will have the following files: - `YYYY/winner/.date-range` - copyright date range for the given directory - `YYYY/winner/sub-dir/.date-range` - copyright date range for the given sub-directory - `YYYY/winner/.entry.json` - entry summary and manifest in JSON - `YYYY/winner/.gitignore` - list of files that should not be committed under git - `YYYY/winner/.path` - directory path from top level directory plus the winning entry files like source code, the Makefile, supplementary data provided by the author and any other file in the winning entry, found under the entry's subdirectory. **NOTE**: The compressed tarball does **NOT** include files such as [ioccc.css](%%REPO_URL%%/ioccc.css), nor `png/` files needed to render an IOCCC web page. You **MUST DOWNLOAD** those, as needed, in order to properly render an IOCCC web page. The primary purpose of compressed tarballs is to provide the files needed to attempt to compile entries. If you downloaded `1984/mullender/1984_mullender.tar.bz2`, for instance, you might then do: ``` cd 1984/mullender make everything ./mullender.alt ``` to compile all versions and then run the alternate version (if you have a PDP-11 or VAX-11 you would be able to run the original version). For more help on compiling entries, see also the FAQ on "[IOCCC Makefile rules](#make_rules)". If you want to view the `index.html` file you can point your browser to the `index.html` file of the winning entry (e.g. `1984/mullender/index.html`) with the caveats noted above. #### Year based tarballs The year based tarballs, which are under each year's directory and are named in the form of `YYYY/YYYY.tar.bz2` (e.g. [1984/1984.tar.bz2](1984/1984.tar.bz2)), include all the winning entries of a given year. Each year's tarball can be found under that year in the [years.html](years.html) page and in the year's `index.html` as well (e.g. [1984/index.html](1984/index.html)). These tarballs have, along with each entry's directory and their respective files (as if you downloaded each entry tarball of the year individually as described above), the following files: - `.filelist` - list of files in the year that are not part of a winning entry of the year, including the `YYYY.tar.bz2` tarball - `index.html` - the `YYYY/index.html` file rendered from the `YYYY/README.md` file - `Makefile` - Makefile for the year to compile etc. all entries of the year - `README.md` - the source of the `YYYY/index.html` file - `rules.txt` - rules of the year's contest - `.year` - text file that has a list of the winning entries' directories of the year Additionally, some will have extra files like: - `.gitignore` - list of files that should not be committed under git - `guidelines.txt` - the guidelines of the year - `iocccsize.c` - `iocccsize` tool of the year - `iocccsize.mk` - Makefile to compile the `iocccsize` tool of the year - `iocccsize-test.sh` - test suite for the `iocccsize` tool .. and perhaps some others we have neglected to mention as well. If you extract a year's tarball you can `cd YYYY` (e.g. `cd 1984`) and then run `make everything` to compile the entries and alternate code of every entry, as if you switched to each entry's directory and ran `make everything` in each one. If you download the 1984 tarball, i.e. `1984/1984.tar.bz2`, then you might extract it and then switch to the directory and compile everything of each entry: ``` cd 1984 make everything ``` For more help on compiling entries, see also the FAQ on "[IOCCC Makefile rules](#make_rules)". Of course in this case you can also switch to individual entries and look at the `index.html` file (or any other file in the entry) and try out the entries that interest you, as if you downloaded that entry's individual tarball. If you want to view the `index.html` files of that tarball, for instance the year's `index.html` file and then `1984/mullender/index.html` you could point your browser to `1984/index.html`, scroll down to `Winning Entries of 1984 - The 1st IOCCC` and click on the link `1984/mullender` which will take you to the `index.html` file. Of course the caveats listed above still will apply. Jump to: [top](#)
## Section 8: Changes made to IOCCC entries
Jump to: [top](#)
### Q 8.0: What was changed in some IOCCC entries?
When the website was being worked on in 2022-2024, the hint files were changed to README.md, which are now used to construct index.html files, most text was converted to markdown, typos were fixed, formatting fixes were made and most entries that no longer worked were fixed to work or partly work. If you wish to find out more, and see how to see the actual differences, check the FAQ on "[how to find extended details of what was changed](#detailed-diff)".
### Q 8.0.1: How can I see the extended details of what was changed?
We have set up make rules to easily do see what was changed in the winning IOCCC entry source. Using the `Makefile` in the entry directory, use one of the following `make(1)` rules: The following `make` rules exist to make a difference: * `make diff_orig_prog`: - This rule will show the diff of the _original_ source to the current source (that is `entry.orig.c` to `entry.c`). * `make make diff_alt_orig`: - This rule will show the diff of the alternate code to the original code (that is `entry.alt.c` to `entry.orig.c`). If no alternate code exists nothing will be shown. * `make diff_alt_prog`: - This rule will show the diff of the alternate code to the entry as it stands (that is `entry.alt.c` to `entry.c`). * `make diff_orig_alt`: - This rule will show the diff of the original code to the alternate code (that is `entry.orig.c` to `entry.alt.c`). * `make diff_prog_alt`: - This rule will show the diff of the entry to the alternate code (that is `entry.c` to `entry.alt.c`). * `make diff_prog_orig`: - This rule will show the diff of the entry to the original code (that is `entry.c` to `entry.orig.c`). For instance one of Landon's all time favourite entries is [1984/mullender](1984/mullender/index.html) so the file names would be: `mullender.orig.c`, `mullender.alt.c` and `mullender.c`. For later years, it would be instead `prog.orig.c`, `prog.alt.c` and `prog.c`. Note that you might see something like: ``` make: [Makefile:170: diff_orig_prog] Error 1 (ignored) ``` at the end of the output but this is completely normal if there are differences. If the alternate code is the same as the original, say with [1984/anonymous](1984/anonymous/index.html), then naturally there is no point in running the rule and the same applies for all the other rules but this system allows for easily seeing the diffs. As some examples we'll first look at one that has really long lines which will make it harder to see what is different, [2001/anonymous](2001/anonymous/index.html). What you would do is `cd 2001/anonymous` and then do: ``` make diff_orig_prog ``` and then be really confused! :-) But for an entry like [1991/dds](1991/dds/index.html), you can see the differences much more easily. `1991/dds` is a good example where it's very simple to see what is different as it's just a couple lines. You might be quite surprised how little some entries had to be changed and at the same time how much other entries had to be changed, often with quite complex differences! In some cases if the line is rather long, like the above mentioned one, it will be harder to see what changed but in other cases like [1984/decot](1984/decot/index.html) or [1986/wall](1986/wall/index.html) it's a lot easier. Well, at least it's easier see the differences on a line-by-line basis but maybe not what actually changed, especially since it's easier to know what was fixed when you have compiler errors :-) (though there are, as noted, some examples where it's quite easy to see the differences). [1991/dds](1991/dds/index.html) is also a good example to see the alt difference very easily. To do that `cd 1991/dds` and then do: ``` make diff_alt_prog ``` and you'll see a single line changed and very simply. **NOTE**: The above mentioned `make` rules are located in the year level directory ([template/1337.mk](%%REPO_URL%%/template/1337.mk) holds a copy of current version) include Makefile via the optional include directive line: ``` -include ../1337.mk ``` The `1337.mk` file must exist in the year level directory in order for these rules to work. If you're an IOCCC aficionado :-), or you really want even more details, very often the [thanks file](thanks-for-help.html) has much more details on what had to be changed. #### Tip: if you have `colordiff` installed it's a lot easier to see the differences To use these rules but provide a different `diff`, for instance `colordiff`, just do: ``` make DIFF=colordiff diff_orig_prog # for orig to prog diff make DIFF=colordiff diff_alt_prog # for alt to prog diff ``` Obviously if you want to view the alternate code or the orig code you can just open the files as described above. See the FAQ on "[original source code files](#original_source_code)" for more information. Jump to: [top](#)
### Q 8.1: Why were some calls to the libc function gets(3) changed to use fgets(3)?
Some may wonder: "Doesn't this tamper with the entry too much?" A fine line indeed has to be drawn here but it was decided that it is worth it because of alarming warnings that can be displayed, in some systems at runtime interspersed with the output of the program. For instance in macOS the entry [1990/tbr](1990/tbr/index.html) would output the warning in such a way that caused confusing output for the entry, looking like: ``` $ ./tbr $ warning: this program uses gets(), which is unsafe. # nothing here, what to do? ``` In some cases it is not possible to fix or at least it is highly unlikely and so those have mainly not been touched except one that has had the buffer size increased (which could be done for others that are not possible to change to `fgets()` though this has not been done). Some entries can be made to look almost identical to the original entry. For instance the fix to [1988/reddy](1988/reddy/index.html) required only a single `#define` be added. In the cases it has not been done it is likely the entry can be found in the [bugs.html](bugs.html) file. In the future we, the judges, would prefer that entries use `fgets()` to prevent these problems. An annoying fact is that for '"compatibility" reasons' `fgets()` retains the newline and `gets()` does not. As the Unix version 7 man page used to say: > **BUGS** > > The _fgets(3)_ function retains the newline while _gets(3)_ does not, all in the name of backward compatibility. We're not sure how this is compatibility but either way it can cause a problem and it is this that has complicated most of the fixes though again some can look almost identical. Jump to: [top](#)
### Q 8.2: Why do some remarks seem inconsistent with the entry?
Because some entries had to be fixed for modern systems and often the fixes required a change in code, sometimes significant changes. Thus the remarks can be inconsistent in some cases. This is why we recommend that when you read the remarks, sometimes the judges' remarks and always the author's or authors' remarks, you look at the original code. When the entry source code is called `prog.c` the original code is in `prog.orig.c`; otherwise it is `dirname.orig.c`. For instance one of Landon's all time favourite entries is [1984/mullender](1984/mullender/index.html) and the original code is in [mullender.orig.c](%%REPO_URL%%/1984/mullender/mullender.orig.c). In some cases, such as `1984/mullender`, the original code is the same as the code as no changes were made (there is an alt version for systems that are not VAX-11/PDP-11, however). See the FAQ on "[original source code](#original_source_code)" and the FAQ on "[entry source code changes](#what_changed)" for more information. Jump to: [top](#)
### Q 8.3: What is the meaning of the file ending in .orig.c in IOCCC entries?
Due to the fact that the original code has sometimes had to change these files are the original winning entry or as close to as possible to the original that we can find (in some cases a change was made by the Judges, for example, or an author might have made a modification without saving the original). Jump to: [top](#)
### Q 8.4: What are alternate versions and why were they added to some entries?
The alternate versions are exactly what they sound like, versions of their respective entries that were not the winning source code but have additional features added (often by the author) or fixes, updates at the request of the judges (upon winning the contest), unobfuscated versions and a variety of other things for instance letting it work on more than one platform (where it would not be possible to do in the original submission). In some cases the alternate code added come directly from the author (some of which already were in the website) but there were other cases where alternate code was added that might or might not be necessary; this was a judgement call and the reasons vary. In many cases it was simply to make the entry more presentable to more people but without modifying the entry itself, which would be tampering with the entry (a problem that we tried to avoid as much as possible although we certainly did not manage to do this perfectly), and in some cases it would be changing it so much that it would no longer be what was submitted. In one case an alternate version was created to help locate and fix a bug that prevented the entry from working properly and it seemed like it should be added as well, for fun (it is a game). In some cases it might be better to not have them but as noted this was a judgement call. See also the FAQ on "[original source code](#original_source_code)" for more information. Jump to: [top](#)
### Q 8.5: Why was arg count and/or type changed in main() in some older entries?
There are a number of reasons this was done but they usually come down to a mis-feature or defect in the `clang` compiler. In all versions of `clang` the first arg must be an `int` and the rest must be a `char **` but in some versions it also objects to the number of args in `main()`. In the versions observed that complain about the number of args it says that there must be 0, 2 or 3 args. This only was triggered with 4 args, not 1, but to future proof the entry entries that had only one arg to `main()` were changed to two. The above also meant that some entries that were recursive calls to `main()` could no longer be so: `main()` instead had to call another function that has the body of the old `main()` and that function would call itself again. In some cases, however, this had to be done even without `clang` objections. Jump to: [top](#)
### Q 8.6: Why were files added to, removed from or changed in some entries?
Like with files being renamed, there are multiple reasons files were added, removed or changed. The addition of the `try.sh` and `try.alt.sh` scripts is the most significant example of files being added. These scripts, help demonstrate entries by automating commands, sometimes many commands and not always simple commands, that one would previously have to run manually (there are other benefits as well). See the FAQ on "[try.sh and try.alt.sh](#try)" for more details. Alternate code, sometimes provided by the author, sometimes provided by the judges and sometimes other people, was added to some entries as well. In the case that a link might end up with a 404 the files, if possible, were downloaded and put into the entry's directory. Sometimes the links were already dead but with the help of the Internet Wayback Machine we could get the files back. In a few cases files were removed and there are multiple reasons for this too. The end result is to help improve the presentation of the entries in some way or ways. Jump to: [top](#)
### Q 8.7: What is the original source file?
Every entry has what is called the "**original source file**". This is a copy of the original source code (usually `prog.c`) that the [IOCCC judges](judges.html) used when declaring that submission is a winning IOCCC entry. There are a number of reasons why the source code (usually `prog.c`) needs to be modified. Reasons include things such as: * modification as requested by the [IOCCC judges](judges.html) * modification as requested by the author(s) * modification as requested by a pull request from [someone else](thanks-for-help.html) * bug fix * portability improvement * etc. We seek to preserve the "**original source file**", for historical purposes, by preserving the original source code (usually as `prog.orig.c`). **IMPORTANT NOTE**: The "**original source file**", because it is a historic record, should **NOT** be modified. Unless one can demonstrate that a mistake has been made regarding the "**original source file**" and that, for some reason, the file is **NOT** the original source code, please do **NOT** attempt to modify it. **IMPORTANT NOTE**: If you believe that the "**original source file**" is **NOT** the original source code, then plesse open an [IOCCC issue](https://github.com/ioccc-src/winner/issues) and describe the problem to the [IOCCC judges](judges.html), including what you believe is the correct "**original source file**". **FYI**: To determine the difference between the "**original source file**" and the source code as it is now now, try: ``` make diff_orig_prog ``` See the FAQ on "[what changed](#what_changed)" for more information on changes. If you want to see more details, including how to see the actual differences, see the FAQ on "[what changed in more detail](#detailed-diff)". Jump to: [top](#)
### Q 8.8: Why were some filenames changed?
The reasons this was done varies. One of the earliest changes was making the old `.hint` or `.text` files `README.md` files. The first time this was done was for `2019/README.text` and `2020/README.text` with [commit 87c41a787fa334f6696ec8f23284eacea63e3e89](https://github.com/ioccc-src/temp-test-ioccc/commit/87c41a787fa334f6696ec8f23284eacea63e3e89). With [commit 77fb0f11a2ddc8584a1ebe8d68fb0cccf3b959a6](https://github.com/ioccc-src/temp-test-ioccc/commit/77fb0f11a2ddc8584a1ebe8d68fb0cccf3b959a6)`index.html` and `hint.html` files were removed in favour of `README.md` files; [commit 851e191519953c743cdd363dc19099e89210319c](https://github.com/ioccc-src/temp-test-ioccc/commit/851e191519953c743cdd363dc19099e89210319c) renamed `hint.txt` and `hint.text` to `README.md`. There were most likely other commits that fixed some issues with this. Other files were also renamed, though, sometimes being converted to markdown as well. Shell scripts were often renamed to end with `.sh` to indicate it is a shell script and to help browsers know how to deal with it (this was before the method of how to display files was devised). Another example is for more consistency, sometimes to do with alternate code and other times something else. There were certainly other reasons as well. Jump to: [top](#)
## Section 9: Helping the IOCCC
Jump to: [top](#)
### Q 9.0: How can I help the IOCCC?
#### We welcome your help in fixing IOCCC entries The [known bugs](bugs.html) file, order by IOCCC years, contains a list of known bugs & (mis)features. If you are looking for an IOCCC entry to try and fix, this file is a good place to start. See the FAQ on "[fixing an entry](#fix_an_entry)" for information on how to submit a fix to an IOCCC entry. Before you consider trying to fix an IOCCC winning entry, please check the [known bugs](bugs.html) file for the IOCCC entry in question. Note that in several cases what you may have discovered, while a (mis)feature is not considered a bug and should **not be fixed**. In cases where the bug is known, the entry's [known bugs](bugs.html) file section may offer you important fixing clues. #### We welcome your help on fixing the IOCCC website This includes typos, dead/invalid links and many other things. Please see the FAQ on "[fixing the website](#fix_website)" for more details. Jump to: [top](#)
### Q 9.1: Is there a list of known bugs and (mis)features of IOCCC entries?
Yes! Please see [bugs.html](bugs.html) for a list of known bugs and/or issues of a variety of kinds. Note that just because an entry is not in the bugs file does not mean there is not an issue and note that some issues are simply missing files, dead URL(s) or something like that. Jump to: [top](#)
### Q 9.2: How can I submit a fix to an IOCCC entry?
If you see a problem with an IOCCC entry, first check the [known bugs](bugs.html) file. In some cases what you might think of as a bug is instead a known feature. In some cases the bug is known, but no fix has ever been submitted. In other cases you may have found a new problem. If you do have a fix, and the [known bugs](bugs.html) file **does NOT recommend against fixing it**, then please consider opening a [GitHub pull request](https://github.com/ioccc-src/winner/pulls) against the master [branch](https://github.com/ioccc-src/winner/branches) of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner). **BTW**: A **problem** is not limited to the code itself. Fixing typos in files such as "_index.html_" files (via its respective `README.md` file), fixing issues in a "_Makefile_", or otherwise correcting an IOCCC entry is **VERY MUCH WELCOME**! Please use the same [GitHub pull request](https://github.com/ioccc-src/winner/pulls) process against the [master branch](https://github.com/ioccc-src/winner/branches) of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner). **NOTE**: if you need help with GitHub pull requests, then please see the FAQ on "[pull requests](#pull_request)". **NOTE**: some of the issues in the [bugs.html](bugs.html) file includes just missing files and we welcome these too! **Please also help us fix typos and / or otherwise improve the write-up** of how IOCCC winning entries are presented! In any event we will happily add you to the [thanks](thanks-for-help.html) file for your help! Of course, an IOCCC author may update their own entries (metadata as well as source code and any extra files) by opening a [GitHub pull request](https://github.com/ioccc-src/winner/pulls) against the [master branch](https://github.com/ioccc-src/winner/branches) of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner). See the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. Note that we're much more inclined to accept an author's fixes but the judges have the final say in the matter. Jump to: [top](#)
### Q 9.3: How do I make a pull request to the GitHub repo?
First, if you do not already have a GitHub account or you have not installed an ssh key to your account you must do so. For this we will assume you do not have a GitHub account. For the steps following creating a GitHub account you will have to be logged into your account. To help you out here is a navigation menu in this FAQ entry: - [Creating a GitHub account](#creating-a-github-account) - [Installing an ssh key to GitHub](#installing-an-ssh-key-to-github) - [Forking the IOCCC winner repo](#forking-the-ioccc-winner-repo) - [Cloning the IOCCC winner repo](#cloning-the-ioccc-winner-repo) - [Making changes, fixes etc.](#making-changes-fixes-etc.) - [Committing your changes](#committing-your-changes) - [Opening a pull request](#opening-a-pull-request) - [What to do after a merge](#what-to-do-after-a-merge) #### Creating a GitHub account Go to [GitHub](https://github.com/) and click on 'Sign up'. Follow the instructions. Once you've completed this task make sure you log in to GitHub. #### Installing an ssh key to GitHub Assuming you do not have an ssh key you should go to the command prompt and type (if you already have one and are okay using it for GitHub you can use that one): ``` ssh-keygen -t rsa -b 4096 -C "luser@example.com" ``` where `luser@example.com` is the email you want associated with your key. Follow the instructions. It will tell you the key files. Once you have an ssh key you need to go to your [account settings](https://github.com/settings/profile). Once there, in the menu on the left you should see the item _SSH and GPG keys_. Click that and then click (on the right side) the button that says _New SSH key_. You will see that you have to specify a title, the key type and the PUBLIC key. Put whatever title you want and keep the key type as _Authentication Key_. Now you need to put the PUBLIC key in. If you used an rsa key the default file will likely be found in: `~/.ssh/id_rsa.pub`. If you used a different algorithm the file name will be different. For instance if you used `ed25519` the default PUBLIC key file would be `~/.ssh/id_ed25519`. If, like some people do, you have a separate key for GitHub, it could be anything you wish, as long as it's in `~/.ssh`. For instance it might be `~/.ssh/github.pub`. Whatever the key file is, copy the contents and paste it into the GitHub field labelled _Key_. Once you have done so click on _Add SSH key_. #### Forking the IOCCC winner repo Open in your browser the link: . You now should follow the instructions in forking the repo. #### Cloning the IOCCC winner repo Once you have forked the repo you are ready to clone it to your system. For instance Cody Boone Ferguson has the GitHub handle _xexyl_ so he would type in: ``` git clone https://github.com/xexyl/winner [target_dir] ``` Once that is completed you will need to change to that directory. The default directory would be the name of the repo but if you specified a target directory it will be that. For instance using the above example you might do: ``` cd winner ``` You're ready to make your changes now! #### Making changes, fixes etc. Here you must use your wits, knowledge, creativity and whatever else you have. Let's say that Cody wants to update his file [2020/ferguson1/play.sh](%%REPO_URL%%/2020/ferguson1/play.sh) script. He would open it in his editor of choice (in his case vim) and make the changes. He would then make sure (as there is a last updated date) to update the last updated date. For instance he might add the following: > BTW: did you know that some people believe in snake human hybrids? It's true! See > http://www.macroevolution.net/snake-human-hybrids.html and have a laugh, shock > or an exercise in sibilance! Then, assuming that the date is 1 March 2024, he would update the line that starts with `# Last updated: ` to refer to `01 March 2024` rather than what it is now (at the time of writing this), `15 April 2023`. But what if he wanted to add a file? He'd create the file and then type: ``` git add foo ``` where _foo_ is the file to add. When he's ready to make a commit he would need to create a new branch for the pull request. #### Committing your changes First, as an aside, if this is your first pull request (which we assume is if you're reading this :-) ) you need to make sure that you can push changes to GitHub with your ssh key. To do this you need to do: ``` ssh -T git@github.com ``` Cody would see: > Hi xexyl! You've successfully authenticated, but GitHub does not provide shell access. Now, assuming that the forked repo is , you'd type: ``` git remote set-url origin git@github.com:xexyl/winner.git ``` Now you'd be ready to make your commits. Before doing anything else, however, a new branch needs to be created. Continuing the example above for [2020/ferguson1/play.sh](%%REPO_URL%%/2020/ferguson1/play.sh), it might be that: ``` git checkout -B human-snakes ``` This would change the branch to the newly created branch `human-snakes` branch. Now Cody could commit the changes: ``` git commit play.sh # if specifying specific files git commit -a # if committing everything ``` He could also have done: ``` git add play.sh git commit ``` In any case this would open an editor (in his case vim) to write a commit log. It is recommended that the first line is <=51 chars and the next line is blank. Then if necessary add a description for the log. For instance the above might warrant the log: ``` Add fun link to 2020/ferguson1/play.sh Did you know some people believe in snake human hybrids? I added a link to the script that discusses this and gives supposed examples. ``` Now a pull request has to be opened. #### Opening a pull request To do this depends on the branch name. Assuming the branch from above, `human-snakes`, you would type: ``` git push --set-upstream origin human-snakes ``` This might show: ``` Enumerating objects: 9, done. Counting objects: 100% (9/9), done. Delta compression using up to 10 threads Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 739 bytes | 147.00 KiB/s, done. Total 5 (delta 4), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (4/4), completed with 4 local objects. remote: remote: Create a pull request for 'human-snakes' on GitHub by visiting: remote: https://github.com/xexyl/winner/pull/new/human-snakes remote: To github.com:xexyl/winner.git * [new branch] human-snakes -> human-snakes branch 'human-snakes' set up to track 'origin/human-snakes'. ``` The link referred to above would then be opened to open a pull request. Just follow the instructions at this point. If however it does not show a link it is likely because the branch already exists in your GitHub account (for the repo). In this case you can open the link: which might show something like: ``` xexyl:human-snakes had recent pushes 1 minute ago ``` and to the right of it you would see a button that says _Compare & pull request_ which you could click on. Do that and follow the instructions. An important note is if you have more than one pull request opened it'll only show the branch name as the summary. You should in that case copy paste the log you put in into the website. For instance the line (on the website) _Add a title_ could have: > Add fun link to 2020/ferguson1/play.sh and then the text field that is labelled _Add a description_ would have: > Did you know some people believe in snake human hybrids? I added a link to the > script that discusses this and gives supposed examples. Once you've done this you should click on _Create pull request_. **IMPORTANT NOTE**: although the [Judges](judges.html) will give more deference to the authors of edited entries the [Judges](judges.html) also retain the final editorial say in the matter. #### What to do after a merge When the judges have merged the pull request you now need to make sure your fork has the merge. To do this from the command line, assuming the fork in the above example, you would type: ``` git checkout master && git pull https://github.com/ioccc-src/winner.git master && git push origin master ``` This will merge your pull request to your fork. p.s. This FAQ is referenced by the [GitHub PULL_REQUEST_TEMPLATE](PULL_REQUEST_TEMPLATE.html). Jump to: [top](#)
### Q 9.4: How can I report an IOCCC website problem?
If you discover a problem with the IOCCC website that is related to a particular IOCCC entry, please see the FAQ on "[report entry bug](#report_bug)" for information about reporting a bug in an IOCCC entry, and see the FAQ on "[fixing an entry](#fix_an_entry)" for information on how to submit a fix to an IOCCC entry. If you discover a problem with the IOCCC website (such as a broken link, which may or may not be specific to a particular IOCCC entry) that is **not related to a particular IOCCC entry**, the best way you can help is to submit a fix to the IOCCC website. See the FAQ on "[fixing the website](#fix_website)" for information on submitting fixes to the IOCCC website. If you do not have an IOCCC website fix, and just wish to report a general IOCCC website problem, we ask that you first look at the [IOCCC issues](https://github.com/ioccc-src/winner/issues) to see if the problem has already been reported. If it has been reported, feel free to add a comment to the issue. Otherwise, if you do not see the same issue reported, then feel free to [open a new IOCCC website issue](https://github.com/ioccc-src/winner/issues/new?assignees=&labels=website&projects=&template=website_issue.yml&title=%5BWebsite%5D+%3Ctitle%3E). Jump to: [top](#)
### Q 9.5: How can I submit a fix to the IOCCC website?
For IOCCC website problems that relate to a particular IOCCC entry, please see the FAQ on "[fixing an entry](#fix_an_entry)" for information on how submit a fix to an IOCCC entry. You may open a [GitHub pull request](https://github.com/ioccc-src/winner/pulls) against the [master branch](https://github.com/ioccc-src/winner/branches) of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner) to submit a fix. Please see the FAQ on "[fixing an entry](#fix_an_entry)". See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. #### Actual website problems Nearly all HTML files on the [IOCCC website](index.html) are built from [markdown](https://daringfireball.net/projects/markdown/) files. If you see lines containing: ``` ``` This means that the file is generated by a tool from a [bin directory tool](bin/index.html). You should **NOT** attempt to modify the file. You may also find lines slightly below the above set that suggest another file to edit. For example, in [contact.html](contact.html), one may read: ``` ``` This means that you could consider editing the referenced markdown file AND then run `make www` from the top level directory in your IOCCC pull request. There are quicker ways but to be sure you get everything built you should do this. If you modified a markdown and you do not see the same file as a html file then you did not complete the fix. Please see the FAQ on "[fixing an entry](#fix_an_entry)". See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. If you see in the html file: ``` ``` it means that the source is **NOT** a markdown file; instead it might be necessary to modify a JSON file, another data file, or, in rarer cases, a tool in the [bin directory](bin/index.html). If this happens, consider opening up an [IOCCC issue](https://github.com/ioccc-src/winner/issues) and ask for help. **IMPORTANT**: some entries have html files **NOT** generated by a markdown file and these should **NOT** be changed. In at least one case, other files that are generated by markdown should **ALSO NOT** be updated as they are very specific and they should only be updated by the author; an example is [Cody Boone Ferguson](authors.html#Cody_Boone_Ferguson)'s [Double-layered chocolate fudge cake recipe](2020/ferguson1/chocolate-cake.html). Jump to: [top](#)
### Q 9.6: How can I correct or update an IOCCC author's information?
You may correct or update IOCCC author information by submitting a GitHub pull request that modifies an author's `author_handle.json` file. For example, if a given `author_handle.json` file contained: ``` "url" : "https://www.example.com/employee/username" ``` and you knew that the author has long ago left the `www.example.com` company, and that they have a new faculty web page at `www.example.edu`, then you should submit a GitHub pull request to change the above line to: ``` "url" : "https://www.example.edu/faculty/deartment/user.name" ``` Authors of IOCCC winning entries are kept in JSON files of the form: ``` author/author_handle.json ``` where `author_handle` is an author handle. See the FAQ on "[author handle](#author_handle_faq)" for more information about author handles. See the FAQ on "[author_handle.json](#author_json)" for information about the contents of these JSON files and how they are used. See the FAQ on "[finding author handles](#find_author_handle)" for how to find an _author_handle_. You may update IOCCC author information in a `author_handle.json` file by [submitting a pull request](#pull_request) against the [master branch](https://github.com/ioccc-src/winner/branches) of the [ioccc-src/winner repo](https://github.com/ioccc-src/winner). See the FAQ on "[GitHub pull request](#pull_request)" for more information. **IMPORTANT NOTE**: As these files are JSON you should verify that they are validly formed (e.g., you didn't make a typo). See the FAQ on "[how to validate JSON files](#jparse)" for more help. Before you form your GitHub pull request that modifies a `author_handle.json` file, please run the `make www` command. This unfortunately takes quite a while but it is the safest way to do it. So you may wish to test your edits by running the somewhat quicker `make quick_www` as this can speed up your testing. The `make quick_www` rule will update the `authors.html` and `location.html` pages and it will also check the timestamps of the `index.html` files versus the `README.md` files. Since they were touched and thus the timestamp was updated, the [bin/quick-readme2index.sh](%%REPO_URL%%/bin/quick-readme2index.sh) tool would only worry about those two files. This greatly speeds things along while testing. Nevertheless, doing a final `make www` is still recommended best practice before you form your pull request. Please see FAQ on "[fixing an entry](#fix_an_entry)". See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. #### Important note about **XX - Anonymous location**: Unless you are the author who originally selected the **XX - Anonymous location**, please do not attempt to change an **XX - Anonymous location** without the permission of the original author, as sometimes they want to have the location known but not their name and/or other details.
#### PLEASE HELP us identify proper locations for IOCCC authors
If you know the location of an author listed under:       **[ZZ - Unknown location](location.html#ZZ)** or if you find IOCCC author location that is incorrect, then **please submit a pull request**, or at least [inform the IOCCC judges](contact.html). **FYI**: The [ZZ - Unknown location](location.html#ZZ) is used for historic winning authors whose location or country is not known, whereas the [XX - Anonymous location](location.html#XX) is used when the winning author does **not wish to disclose their location**. The contents of these JSON files contain the best known information about authors of IOCCC entries. See FAQ on "[author_handle.json](#author_json)" for information about the contents of these JSON files and how they are used. For example, if a given `author_handle.json` file contained: ``` "location_code" : "ZZ" ``` and you knew that the author was located in [Australia](location.html#AU) (location code **AU**), we encourage you to submit a **GitHub pull request** to change that line to: ``` "location_code" : "AU" ``` See the FAQ on "[fixing author information](#fix_author)" for information about how to change author location codes. Jump to: [top](#) We would appreciate if you try to fix the broken (the link goes nowhere) or wrong (the link goes to something that clearly is not the original intent) web link. If wish to fix such links, you may open a GitHub pull request as described in FAQ on "[fixing the website](#fix_website)". In the case of dead links or invalid links it doesn't matter if it's a specific winner or not; the procedure is the same: open a pull request to fix the problem. See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. As far as how to find the updated link you can try using the [Internet Wayback Machine](https://web.archive.org) and see if you can find the last non 4xx non 3xx page. Note, however, that just because it redirects, does not mean it's not valuable. Other times you might find it with a web search. Some links were changed to more recent URLs by doing this exact same thing. Some links, while they were a valid web page, no longer reach the intended web page (for example when the domain is sold and the new domain owner's content no longer provides the content that was originally intended .. and while the content of the web page may be humorous to some, the original content may have literally gone "up in smoke"). In cases where the original content is lost, try searching for it on the [Internet Wayback Machine](https://web.archive.org). When searching look back for dates that are around the year of given IOCCC contest. If you do find the original content in Internet archive history, please consider submitting a change to replace the link accordingly. If there is no alternative that you can find you might want to remove the link instead by replacing the link with just phrase of text. For example, if the text in some `index.html` file was: ``` See the [author's description of the program](https://example.com) for more information. ``` Assuming that the author's description cannot be found in the [Internet Wayback Machine](https://web.archive.org) archive, then replace that text with: ``` See the **author's description of the program** (sorry the content is no longer available) for more information. ``` If you just wish to report the bad link issue, see FAQ on "[report website problem](#report_web_problem)". Jump to: [top](#)
### Q 9.8: How can I support the IOCCC?
To run the IOCCC, there is a considerable amount of servers, services and software that is needed. The [IOCCC judges](judges.html) run the IOCCC entirely out of their own funds. This includes paying for IOCCC related hardware, services, registration, software, related technical items, in addition to paying our [Our Favorite Universe](https://www.youtube.com/@OurFavoriteUniverse) YouTube channel producer, [Danni McInnis](https://www.alchemistproductiondesign.com). There is **NO** requirement for anyone to support the [IOCCC](index.html). Nevertheless, it has been shown that receiving **anonymous** gifts provides the [IOCCC judges](judges.html) with a nice [dopamine](https://en.wikipedia.org/wiki/Dopamine) boost, and happy [IOCCC judges](judges.html) help make the IOCCC better for everyone. :-) Here is how you may support the IOCCC:
  Support the IOCCC    click below to support
    Patreon logo     Buy Me A Coffee logo     GitHub logo
Jump to: [top](#)
### Q 9.9: I deobfuscated some entry code, may I contribute the source?
**PLEASE NOTE**: **many [winning authors](authors.html)** have unobfuscated code of their **own entries** and you should look for this first, often on GitHub or on their website; see the FAQ on [how to find more information about a winning author of an entry](#author_information) for how you might find this information. We ask you to, if you can find them, please ask them what they think as they can often provide invaluable information; this is less of an issue for fixes of bugs - not features - found in the [bugs.html](bugs.html) file. The [IOCCC judges](judges.html) welcome those who wish to contribute a **deobfuscated** version of a winning IOCCC entry: from either the [author or authors](authors.html) (**which is much, much preferred**) or from people such as yourself (assuming you are not the author :-) ) who are willing to contribute **deobfuscated** code. We also welcome contributions to improve existing **deobfuscated** code. You might wish to look at their URL or alt URL (see below for more details) **first** as quite a few [authors](authors.html) have provided unobfuscated code of their entries and this is far more fair to the [winning authors](authors.html) (and it is much more likely to be identical functionality as well, though many [authors](authors.html) are experienced and skilled enough to add features **after or during obfuscation!** and many in fact do). **HISTORICAL NOTE**: The IOCCC website has shifted to a more educational theme: preferring to explain entries rather than hiding things under the guise of such information being a "_spoiler_". We now use the term **deobfuscated** instead of "_spoiler_" for this reason, at least in most cases; other terms might be used, including on a rare occasion _spoiler_, this depending on context. We ask that the **deobfuscated** code be **identical in functionality** to the winning IOCCC entry code. **_PLEASE_ NOTE**: Beware that IOCCC entry code may contain **extremely subtle and obscure side effects** (i.e., features). Those wishing to contribute a **deobfuscated** version of code should **strive to mimic** the original (or existing) IOCCC entry code as much as possible. Some authors can be contacted (see above for more details on this) and you could ask them for details and if possible it would be good to include them in the discussion as well (see below) as it is **very likely** there are things that will be missed when trying to deobfuscate the code, some of which might be important to the author. To contribute your **deobfuscated** code, please open up a [Show and tell new discussion](https://github.com/ioccc-src/winner/discussions/new?category=show-and-tell) with a title of the form: > Enhancement: deobfuscated code for YYYY/dirname where "`YYYY/dirname`" refers to the winning IOCCC entry for which you are deobfuscating. In the **body** of your new discussion, **PLEASE** provide us with a **URL** of your **deobfuscated** code, along with whatever notes and/or comments you think might be helpful. If the author has a GitHub handle **please** mention them in the discussion (see above part for how you might find out if they have a GitHub account)! If you are providing an improved version of some existing **deobfuscated** code, please mention that in the **body** of your new discussion as well. If there are **limitations** to how well the your **deobfuscated** code mimics the original (or existing) IOCCC entry code, **PLEASE** mention those **limitations** in the **body** of your new discussion as well. Any questions that may arise will be added as comments to the discussion. **SUGGESTION**: **PLEASE** try to make your **deobfuscated** code readable. **PLEASE** add comments as needed to help the reader of your **deobfuscated** code understand it. **SUGGESTION**: Where useful, consider providing, as **C comments**, code fragments of from the original (or existing) IOCCC entry code. While it is **NOT** necessary to include the entire original code as **C comments**, including key parts from the original (or existing) IOCCC entry code may be helpful to others who wish to read your **deobfuscated** code. If your **deobfuscated** is accepted (in some form), the [IOCCC judges](judges.html) will be happy to **thank you** for your contribution in the [thanking people for their help file](thanks-for-help.html). The [IOCCC judges](judges.html) will do the rest of the work in integrate your **deobfuscated** code as an "_alt_" code for the entry **AND** will reference your **deobfuscated** code in the entry's `index.html` file. We will be happy to include any whatever notes and/or comments from your new discussion that be prove helpful. **THANK YOU** in advance for your willingness to assist! Jump to: [top](#)
### Q 9.10: How do I report a bug in an IOCCC entry?
We do not 'maintain' the contest entries as such. The code is made available on an 'AS IS' basis. If you have a FIX for an entry, we suggest that you submit your fixes in a [GitHub pull request](https://github.com/ioccc-src/winner/pulls) as we welcome pull requests that have a minimal impact on the entry while improving the portability, functionality, and/or addressing known problems. If you do submit a pull request, we ask that each pull request address just one IOCCC entry at a time. Note that just because you have a fix does not mean it'll be accepted. This might be because the author objects or it doesn't fit in some way or another. Of course if the entry does not work we'll certainly be more inclined to accept the fix. If it is accepted we'll be happy to credit you in the [thanks](thanks-for-help.html) file. If you're a previous author of a winning IOCCC entry we will happily link to your entries; if you're not we can link to your website if you wish. Please see the FAQ on "[fixing an entry](#fix_an_entry)" for information on how to submit a fix to an IOCCC entry. See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. Jump to: [top](#)
## Section 10: Miscellaneous IOCCC
Jump to: [top](#)
### Q 10.0: May I mirror the IOCCC website?
There are a few steps in mirroring the website: 0. First of all, open the website on your device, preferably one you can hold and aim somewhere. 1. Then, turn your device towards a mirror. This should mirror it. :-) 2. If you can, take a picture of the mirror image. It might help if you can put your device down facing the mirror, so that it is easier to get a picture. Okay, backing up, on a more serious note: we are not accepting mirror requests at this time, sorry. However you are free to fork the [IOCCC winner repo](https://github.com/ioccc-src/winner). Yes we are aware that some people have previously made their own repo of the winning entries but these **ARE UNOFFICIAL** and **VERY LIKELY** out of date or incorrect. What's more, this repo is the source of the [**Official** IOCCC website](index.html) so whenever a push is made to this repo the **Official IOCCC website** is updated. When new winners are announced, this will happen. To put it simply, please do **NOT** fork those repos, as they are **UNOFFICIAL** and certainly **OUT OF DATE**. If you do make a new fork of **THIS** repo, we do ask that your fork keep up to date with the latest changes when possible. Thank you. Jump to: [top](#)
While IOCCC judges look favorably on most requests to use IOCCC material, we request that you ask the [IOCCC judges](judges.html) first. Of course, if you're the winner of the entry you can make use of it as you want (make a shirt, put it on your website etc.). Please send your request using the instructions on the [contacting the IOCCC judges](contact.html) page. Please note that the content of the IOCCC **Copyrighted and is under the CC BY-SA 4.0 License**. See the [Copyright](#copyright) at the bottom of IOCCC web pages for more details. See FAQ on "[using IOCCC content](#license)". For additional information on the [Copyright and CC BY-SA 4.0 License](license.html). Jump to: [top](#)
### Q 10.2: Why do you sometimes use the first person plural?
As a precedent for [first person plural](https://en.wikipedia.org/wiki/Nosism), we may cite [Two-, Three-, and Four-Atom Exchange Effects in bcc in 3He](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.35.1442) and the co-authorship of [F. D. C. Willard](https://en.wikipedia.org/wiki/F._D._C._Willard) as well as the [APS New Open Access Initiative](https://journals.aps.org/2014/04/01/aps-announces-a-new-open-access-initiative). The number of [IOCCC judges](judges.html) has always been "> 1" such that IOCCC judges often refer to themselves in the plural, sometimes [in the common plural](https://en.wikipedia.org/wiki/Plural), sometimes in the [first person plural](https://en.wikipedia.org/wiki/Nosism), there may be some who reject such a practice. Therefore please consider that when you believe that just one of the [IOCCC judges](judges.html) is in action, you may consider that [F. D. C. Willard](https://en.wikipedia.org/wiki/F._D._C._Willard) has been consulted, agreed, and has authorized the statement thus allowing the [in the common plural](https://en.wikipedia.org/wiki/Plural) to be used without offense. And while some might claim that [F. D. C. Willard](https://en.wikipedia.org/wiki/F._D._C._Willard) died in 1982, we suggest that the [Schrödinger's cat](https://en.wikipedia.org/wiki/Schrödinger%27s_cat) superposition may still be in effect and the 1982 [report of death was an exaggeration](https://books.google.com/books?id=ms3tce7BgJsC&lpg=PA134&vq=%22the%20report%20of%20my%20death%20was%20an%20exaggeration%22&pg=PA134#v=onepage&q=%22the%20report%20of%20my%20death%20was%20an%20exaggeration%22&f=false). p.s. Here is an image of F. D. C. Willard: image of F.D.C.Willard.png Jump to: [top](#)
### Q 10.3: What is the purpose of the `.top`, `.allyear`, `.year` and `.path` files?
The [.top](%%REPO_URL%%/.top) file resides at the top directory. This file contains the complete list of IOCCC years. Under each IOCCC year, one will find a `.year` file. These files contain directory paths from the top directory, of the IOCCC entry directories for a given year. For example, see the [1984/.year](%%REPO_URL%%/1984/.year) file. The [.allyear](%%REPO_URL%%/.allyear) file contains the contents of all `.year` files for all IOCCC years. Under each IOCCC entry directory, you will find a `.path` file. These files contain the directory path from the top directory. For example see [1984/anonymous/.path](%%REPO_URL%%/1984/anonymous/.path). The .top, .allyear, .year and .path files are generated from the top level Makefile, by: ``` make genpath ``` Jump to: [top](#)
### Q 10.4: What is the current meaning of the IOCCC terms Author, Entry, and Submission?
The IOCCC is now attempting to use the following terms: - Author An _author_ is someone who has submitted an entry that has won the IOCCC. An entry can have more than one authors. A number of authors have submitted entries that have won the IOCCC, sometimes in the same IOCCC contest year. **An apology for being inconsistent**: In the past, the IOCCC used the term _winner_ to refer to what is now an _author_. In a number of historical cases, such as old rules and old guidelines, terms such as _winner_ may still be found. Moreover, out of habit, the IOCCC judges sometimes use old names such as _winner_ when they should use _author_. Sorry (tm Canada 🇨🇦:-) )! - Entry An _entry_ is a _submission_ that won the IOCCC. An _entry_ has one or more _authors_. An _entry_ includes all of the files needed to compile it, plus sample input files, a `Makefile`, an `.entry.json` file describing the entry, a compressed tarball containing all of files in the entry, etc. Under the IOCCC tree, an _entry_ that win the IOCCC in year _YYYY_ is located under the directory `YYYY/entry`. **An apology for being inconsistent**: In the past, the IOCCC used the term _winner_ to refer to what is now an _entry_. In a number of historical cases, such as old rules and old guidelines, terms such as _winner_ may still be found. Moreover, out of habit, the IOCCC judges sometimes use old names such as _winner_ when they should use _entry_. Sorry (tm Canada 🇨🇦:-) )! - Submission A _submission_ is something given to the IOCCC judges for consideration when the IOCCC is open. When the IOCCC is open for submissions, those who register to enter the IOCCC may use the [mkiocccentry tool](https://github.com/ioccc-src/mkiocccentry) to package their code into a compressed tarball that may be uploaded to the [IOCCC submit server](https://submit.ioccc.org). This compressed tarball is formatted in such a way that the IOCCC judges do not see who wrote the code. A _submission_ that the IOCCC judges deem to have won the IOCCC becomes an _entry_. Only then do the IOCCC judges look into the special JSON file to discover who the _author_(s) are. **An apology for being inconsistent**: In the past, the IOCCC used the term _entry_ to refer to what is now a _submission_. In a number of historical cases, such as old rules and old guidelines, terms such as _entry_ may still be found. Moreover, out of habit, the IOCCC judges sometimes use old names such as _entry_ when they should use _submission_. Sorry (tm Canada)! 🇨🇦:-) Jump to: [top](#)
### Q 10.5: Am I allowed to use IOCCC content?
**Disclaimer**: This FAQ is **not a license**, has **no legal value**, and only highlights some of the key features and terms of the actual [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/legalcode.en). The content of the IOCCC is [Copyrighted and is under the CC BY-SA 4.0 License](#copyright). As long as you abide by the terms of the [CC BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1) you may copy and redistribute the material in any medium or format for any purpose, even commercially. As long as you abide by the terms of the [CC BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1) you may remix, transform, and build upon the material for any purpose, even commercially. This FAQ is an incomplete summary of how you may use IOCCC content. You should review the [highlights of some of the key features and terms](license.html) and this may help clarify some aspects of the [CC BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1). The [Copyright and CC BY-SA 4.0 License](#copyright) applies to all IOCCC content. We use this to help ensure that we can all enjoy that those working on the IOCCC have proper Attribution including, of course, the IOCCC winners themselves! It is designed to help ensure that everyone may enjoy the IOCCC. Jump to: [top](#)
### Q 10.6: What is Mastodon and why does the IOCCC use it?
The [IOCCC uses Mastodon](https://fosstodon.org/@ioccc) for news updates, announcements, and for various other social media purposes. **Please follow the [IOCCC on Mastodon](https://fosstodon.org/@ioccc)**. > The IOCCC no longer uses twitter, or whatever that someone who appears to have poor impulse control (allegedly) calls their platform these days. The IOCCC prefers to reside in the [fediverse](https://fediverse.info). **For help with Mastodon**: There is [help with Mastodon](https://mastodon.help) available for those who might wish to [get started with Mastodon](https://fosstodon.org/deck/getting-started). While there are many fine Mastodon server instances out there, the [IOCCC judges](judges.html) use [fosstodon.org](https://fosstodon.org/about) where lots of fun folk hang out, and topics like science, technology, [free and open source](https://en.wikipedia.org/wiki/Free_and_open-source_software) have a good home. The [fosstodon.org](https://fosstodon.org/@fosstodon) folk made the IOCCC feel welcome. While using Mastodon is free, the [IOCCC judges](judges.html) are pleased to [support the Fosstodon Hub](https://hub.fosstodon.org/support/). If you have a phone or tablet there is also an official app that you can get from the App Store or whatever equivalent your device has. Please note that the app does not at this time seem to give push notifications when someone you follow posts something so you will have to check the IOCCC feed manually. **HINT to mastodon users**: You may wish to refresh the [@IOCCC mastodon feed](https://fosstodon.org/@ioccc) page and/or mastodon app from time to time to view IOCCC mastodon updates. Jump to: [top](#)
### Q 10.7: How do I set certain tabstops for viewing source code in vi(m)?
Sometimes an author will state that for best viewing purposes you should have your tabstop set at say 4 or 8. If you use vim or vi or vim in no compatible mode you can do this easily: make sure you're in command mode (in most cases you can hit ESC to do this) and then type the command: ``` :set tabstop=4 ``` where `4` is the value you wish to set the tabstop to. Jump to: [top](#)
#### Menu on desktops or laptop computers
The way the menu works on desktops or laptops is that you should simply see the menu directly without the need of JavaScript or any intervention on your part. It should look something like: screenshot of IOCCC menu on desktops Simply move your mouse cursor over the category you want and then click on the item you wish to view that drops down from the category. This is likely how it will appear with a [tablet device in landscape mode](#tablet_menu), too, unless [JavaScript is disabled](#no_javascript_menu).
#### Mobile menus
If, however, you're on a mobile device, it can vary, depending on the dimensions and whether or not you have JavaScript enabled.
##### Menus on mobile phones
For instance, on an iPhone 14 Pro Max or similar device (in dimensions), you should see at the top right of every page, something that looks like: screenshot of IOCCC menu on iPhone 14 Pro Max In this case click on the icon at the top right corner that looks like: menu open icon to activate the menu.
##### Menu on mobile devices if JavaScript is disabled
If JavaScript is disabled on any mobile device, tablet or phone, you should see the words: ``` Please Enable JavaScript ``` at the top right corner; clicking on this will take you to the [no JavaScript menu](nojs-menu.html) which is a plaintext menu. You of course can use this if you like, even if you do not have JavaScript enabled, by pointing your browser to [https://www.ioccc.org/nojs-menu.html](nojs-menu.html).
##### Menus on tablet devices (e.g. iPads)
With tablets, it likely depends on the orientation you have your device in. If it's in portrait mode you likely will see the [menu that one will get on a mobile phone](#mobile_phone_menu). If, on the other hand, you are using landscape mode, say on an iPad Pro 11 inch 4th generation, then you will likely see the [menu as you would on a desktop or laptop](#desktop_menu).
##### Menus on mobile devices wider than 1024 pixels
Finally, if you're on a mobile device that is wider than 1024 pixels, you will very possibly have to **press and hold** the menu icon: menu open icon to activate it. You can then use it [as you would on a mobile phone](#mobile_phone_menu).
##### Browsing the website on mobile devices with a browser bug
It was noticed that in iOS 16 Safari (both on an iPhone 8 Plus and in simulation mode in macOS) the menu does not work at all. That is to say one might see: browser bug where menu icon does not show up Notice how the menu icon is not even there! This happens in both portrait mode and landscape mode. In this case one will have to use the [no JavaScript menu](#no_javascript_menu). If you have a fix for this that **does NOT affect the usability of desktops, laptops or other mobile devices**, please consider fixing it and [opening a pull request](#pull_request) or at least [report it as an issue](https://github.com/ioccc-src/winner/issues/new/choose) (choose the category _Website issue_). Jump to: [top](#)
### Q 10.9: How do I find more information about a winning author of an entry?
At the top of the index.html file of a winning entry with the author you want information on, you should see a section called `Author`. All you have to do is click on the author's name (it's a link) and it will take you to their information in the [authors.html](authors.html) page. There you will find various information including a link to their [authors.html](authors.html) information which includes various things like their GitHub account (if known), a URL or alternate UL, mastodon handle, location (if known and not anonymous location) and a link to their JSON author file. **NOTE**: you might wish to search google (or some other search engine) by their name as sometimes you can find out their GitHub account even if it's not in our JSON files. Of course if you know the author's name you can go directly to [authors.html](authors.html) and click on their surname's/last name's/second name's initial and then scroll down (if necessary) to the author in question. Jump to: [top](#)
### Q 10.10: What is this cb tool that is mentioned in the IOCCC?
This was a C beautifier for Unix, both AT&T and Berkeley, but it seems to no longer be available, code wise, except for Plan 9, but Plan 9 was never used for judging the IOCCC. A Unix man page for `cb` [still exists](https://www.ibm.com/docs/en/aix/7.3?topic=c-cb-command). Jump to: [top](#)
### Q 10.11: What do the status.json JSON file indicate?
The following **JSON** members are required to be present [status.json](status.json).
## no_comment
This is a **mandatory** comment for which we offer no comment other than this comment. :-) The **JSON** member value must be the following **JSON** quoted string: ``` "mandatory comment: because comments were removed from the original JSON spec" ```
## IOCCC_status_version
This is the version of format of the [status.json](status.json) file. The **JSON** member value of is a **JSON** quoted string the form "_version YYYY-MM-DD_". This document describes version "**1.0 2024-03-09**".
## contest_status
This is the current status of the contest. The following **JSON** member value string may be one of the following **JSON** quoted strings:
### "**pending**"
While the contest **[PENDING](#pending)** the contest is not yet [open](#open), however there is a tentative scheduled date and time by which the contest will [open](#open) for submissions. A preliminary [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html), and [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry) have been released. You may [register for the IOCCC](next/register.html) while the contest is [pending](#pending), however you will **NOT** receive your own Email message containing your very own **Username and Initial Password until the contest is [open](#open)**. You will need these to be able to [upload your submission](next/submit.html) to the [IOCCC submit server](https://submit.ioccc.org). Once contest moves from [pending](#pending") to [open](#open), an announcement Email will be sent out to the mailing list of those have successfully registered for the IOCCC. In addition, an announcement will be made to the [IOCCC news](news.html) in case you miss that announcement Email. While you are waiting for the contest to [open](#open), we **highly recommend** that you review the [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html), and [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry). Should you have any comments, suggestions, and concerns about the above, and **while you waiting** for the contest to [open](#open), please see the FAQ on "[comment or make a suggestion on IOCCC rules, guidelines and tools](#feedback)" as well as the FAQ on "[best way to ask a question about the IOCCC rules, guideline and tools](#questions)" for how. See also the FAQ on "[how to upload your submission](next/submit.html)" for more information on the submission process when the IOCCC [reopens](#open).
### "**open**"
While contest is **[OPEN](#open)**, those who have [registered for the IOCCC](next/register.html) may [upload their submissions](next/submit.html) to the [IOCCC submit server](https://submit.ioccc.org). See the FAQ on "[how to submit](#submit)" for more information. See the [IOCCC news](news.html) page for details on any IOCCC related deadlines such as when the contest will [close](#closed). The [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html), and [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry) are now official. Should you have any questions about these, please see the FAQ on "[best way to ask a question about the IOCCC rules, guideline and tools](#questions)" for how to ask them. Be sure to review the official [IOCCC rules](next/rules.html), [IOCCC guidelines](next/guidelines.html), for any changes, as well as updating your [IOCCC mkiocccentry tools](https://github.com/ioccc-src/mkiocccentry) as changes to them may have been made while the contest was "**[pending](#pending)**". See also the FAQ on "[how to submit](#submit)" for more information on the submission process when the IOCCC [reopens](#open).
### "**judging**"
While contest is **[JUDGING](#judging)**, you cannot [register](next/register.html) nor can you [upload submissions](next/submit.html). This is because the [IOCCC judges](judges.html) are in the process of judging the [submissions](#how_many) they received while the contest was [open](#open). Watch the [@IOCCC mastodon feed](https://fosstodon.org/@ioccc) for updates.
### "**closed**"
While contest is **[CLOSED](#closed)**, you cannot [register](next/register.html) nor can you [upload submissions](next/submit.html). You have to wait for the next contest to [open](#open). See the [IOCCC winning entries page](years.html) for the entries that have won the [IOCCC](index.html). **NOTE**: From time to time, [winning IOCCC entries](years.html) may have their write-ups updated, `Makefiles` improved, source code fixed etc. See [IOCCC news](news.html) for details. Watch both [this IOCCC status page](status.html) and the [@IOCCC mastodon feed](https://fosstodon.org/@ioccc) for information about future contest [openings](#open).
## news_update
This shows the latest modification date for the [IOCCC news](news.html) page. The **JSON** member value is a **JSON** quoted string obtained from the date field of the following `ls(1)` command: ``` TZ=UTC ls -D '%FT%T+00:00' -ld news.html ``` **NOTE**: The date and time are given with respect to **UTC** timezone. **NOTE**: It is possible that for some reason, the [IOCCC news](news.html) page was modified without the content being changed. While we will try to minimize the cases where this happen, we apologize in advance (Sorry tm Canada 🇨🇦) when it does.
## status_update
This shows the latest modification date of [status.json](status.json) file. The **JSON** member value is a **JSON** quoted string obtained from the date field of the following `ls(1)` command: ``` TZ=UTC ls -D '%FT%T+00:00' -ld status.json ``` **NOTE**: The date and time are given with respect to **UTC** timezone. **NOTE**: It is possible that for some reason, the [status.json](status.json) file was modified without the content being changed. While we will try to minimize the cases where this happen, we apologize in advance (Sorry tm Canada 🇨🇦) when it does. Jump to: [top](#)
### Q 10.12: What is the purpose of the `.date-range` files?
In each directory of the [IOCCC winner repo](https://github.com/ioccc-src/winner), a `.date-range` file may be found. The contents of the `.date-range` file are the copyright date range for the constructed HTML files in that same directory. The [bin/md2html.sh](%%REPO_URL%%/bin/md2html.sh) tool substitutes strings of the form "%%DATE_RANGE%%" with the contents of the `.date-range` file. This allows a per-directory copyright date range, rather than a single global copyright date range for the entire web. Thus when the calendar year changes, the entire website does **NOT** need to be rebuilt. See also the "[Special DATE_RANGE token](bin/index.html#date-range)" section of the [bin tools](bin/index.html) for information about how the "%%DATE_RANGE%%" is processed.
#### On making changes to the website
When a change is made to the content of the [IOCCC winner repo](https://github.com/ioccc-src/winner), simply update the `.date-range` files in the same directories where the changes are made: change the final year in the file to the current year. When the website is rebuilt, the proper copyright date range will be picked up.
## Section 11: History of the IOCCC
Jump to: [top](#)
### Q 10.13: What is a fun challenge?
A "**fun challenge**" for a winning IOCCC entry is a puzzle or task that an [IOCCC judge](judges.html) suggested people consider solving. After you figure out what a given winning entry does, we encourage you to attempt the fun challenge. Some "**fun challenges**" ask you to explain something about a winning IOCCC entry. Other fun challenges ask you to produce a variant of the `prog.c` program that has a different or enhanced behaviour. And still, other types of fun challenges may be posed. **NOTE**: Some of these challenges are easier than others. You may find the "**fun challenges**" for a given IOCCC year, by visiting a given year link on the [IOCCC Winning Entries by Year](years.html) page, clicking in the **About the Xth IOCCC ((YEAR))** link, and then clicking on the **fun challenges for IOCCC ((YEAR))** link. **NOTE**: "**Fun challenges**" are available only for year **2025 and later**. See also the FAQ on "[submit a fun challenge solution](#solve_fun_challenge)". Jump to: [top](#)
### Q 10.14: How do I submit a solution to a fun challenge?
Look at the given winning IOCCC entry's "**fun challenge**" text for a given IOCCC year by visiting a given year link on the [IOCCC Winning Entries by Year](years.html) page, clicking in the **About the Xth IOCCC ((YEAR))** link, and then clicking on the **fun challenges for IOCCC ((YEAR))** link. **NOTE**: "**Fun challenges**" are available only for the year **2025 and later**. If the "**fun challenge**" is listed as still **OPEN**, and you believe you have a solution to a "**fun challenge**", we recommend that you create a [GitHub repo](https://www.github.com) (or other public git repository), containing your solution. You may wish to start with the given winning IOCCC entry's compressed tarball. Modify files as needed, and finally discuss your solution by adding text to the top of your repo's `README.md` file. Then consider submitting your solution by submitting a [GitHub pull request](#pull_request) against the IOCCC year's `challenge.md` file containing a link in [markdown form link form](markdown.html#links) to your solution. Feel free to credit/identify yourself when you modify the `challeng.md` file in your [GitHub pull request](#pull_request). **SUGGESTION**: Look at the [2025/challenge.md file](%%REPO_URL%%/2025/challenge.md) for an example of both the markdown form, as well a how a few solutions are presented. **NOTE**: If the "**fun challenge**" is listed as **CLOSED**, and you believe your solution is **substantially better** than any of the solution(s) listed, then please consider submitting your solution as well. **NOTE**: If you have a suggestion for a "**fun challenge**" that is not already listed, please consider submitting it as an additional challenge. **NOTE**: And to state the obvious: the [IOCCC judge](judges.html) reserves the right to request modifications to your pull request, linked content, or to reject your pull request altogether. See also the FAQ on "[fun challenges](#what_fun_challenge)". See also the FAQ on "[GitHub pull request](#pull_request)" for more information about pull requests. See also the FAQ on "[how to use markdown](#markdown)" as well as the [IOCCC markdown guidelines](markdown.html).
### Q 11.0: How did the IOCCC get started?
**It was a dark and stormy night...** OK, let's go back to 1984, not 1830: one day (1984 March 23 to be exact), Larry Bassel and I (Landon Curt Noll) were working for National Semiconductor's Genix porting group, and we were both in our offices trying to fix some very broken code. Larry had been trying to fix a bug in the old Bourne shell [sh(1)](https://github.com/dank101/4.2BSD/tree/708b3890ac0c2f034f2840b5ee9125b3c83a05bc/bin/sh) (C code `#define`d to death to sort of look like Algol), and I had been working on the [finger(1)](https://github.com/dank101/4.2BSD/blob/708b3890ac0c2f034f2840b5ee9125b3c83a05bc/ucb/finger.c) command along with its associated [fingerd(8)](https://github.com/dank101/4.3BSD-Reno/tree/master/libexec/fingerd) daemon from early 4BSD as used by the GENIX operating system for the NS SYS16 system. **BTW**: The above links to BSD code are only approximations of the BSD code that was being used in the GENIX operating system for the NS SYS16 system. For example, the source code reference to `fingerd(8)` is well past the 1984 March 23 date. We happened to both wander (at the same time) out to the hallway in Building 7C to clear our heads. We began to compare notes: '_You won't believe the code I am trying to fix_'. And: '_Well you cannot imagine the brain damage level of the code I'm trying to fix'_. As well as: '_It's more than bad code, the author really had to try to make it this bad!_ After a few minutes we wandered back into my office where I posted a [flame to net.lang.c](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=789%40nsc.UUCP&rnum=3&filter=0") inviting people to try and out obfuscate the UN\*X source code we had just been working on. **BTW**: I (Landon Curt Noll) had to post this [typo correction](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=795%40nsc.UUCP&rnum=10&filter=0). Thus began the tradition of putting typos in the contest rules and guidelines ... to make them more obfuscated of course! :-) **BTW**: This posting was made back in the days when AT&T was the evil giant. Now, Microsoft makes AT&T look mild and kind in comparison. :-( (IMHO) ). **BTW**: See the story about the '[Bill Gates](1993/cmills/index.html)' award. :-) OK, back to the story. We (Larry and I) received a number of entries by email. When we began to receive messages from outside of the US, Larry and I decided to include International in the name. The [1st IOCCC entries](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=837%40nsc.UUCP&rnum=2&filter=0) were posted on 17 April 1984. There were 4 entries that won in 1984: 1. [(dis)honorable mention](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=842%40nsc.UUCP&rnum=8&filter=0) 2. [3rd place](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=843%40nsc.UUCP&rnum=7&filter=0) 3. [2nd place](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=844%40nsc.UUCP&rnum=6&filter=0) 4. [1st place](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=845%40nsc.UUCP&rnum=5&filter=0) **BTW**: The (dis)honorable mention wished to remain anonymous. While many have asked who it was, we have continued to follow the author's wish to remain anonymous. A few years ago, we asked the author if they still wanted to remain anonymous. They said: '_Yes, I want to keep my anonymity. But you can tell them that I am well known for my connection to the C language_'. It was not until 2001 that another [anonymous entry](2001/anonymous/index.html) received an award. **BTW**: The [1984/mullender](1984/mullender/index.html) remains one of my (Landon Curt Noll) all time favorites. The name used in the posting of the [1st winning IOCCC entry](http://groups.google.com/groups?q=Obfuscated&hl=en&lr=&ie=UTF-8&as_drrb=b&as_mind=1&as_minm=1&as_miny=1983&as_maxd=18&as_maxm=4&as_maxy=1984&selm=837%40nsc.UUCP&rnum=2&filter=0) posting was **I**nternational **O**bfuscated **C** **C**ode **C**ontest or **IOCCC** for short. The posting said '_1st annual_', so in 1985 we held the [2nd IOCCC contest](years.html#1985) and the tradition continues as the longest running contest on the Internet. P.S. Part of the inspiration for making the IOCCC a contest goes to the [Bulwer-Lytton fiction contest](http://www.bulwer-lytton.com/) (hence the reference to that (in)famous dark and stormy night all the way back in 1830 when Landon was just a wee lad). Jump to: [top](#)
### Q 11.1: Why are some years missing IOCCC entries?
There were some years, such as 1997, 1999, 2002-2003, 2007-2010, 2016-2017, 2021-2023 (or 2024, see below), when no IOCCC was held. While we try to hold the IOCCC every year, sometime the other demands on the IOCCC judges do not permit us to hold a new IOCCC. The pause during 2021 through the end of 2024 (when IOCCC28 officially entered pending status) was due to the development of tools (for submission, the server and the website generation) and the JSON parser (for the tools, the contest and the website) to make it easier and much more likely for the IOCCC to be held on a yearly basis. Jump to: [top](#)
### Q 11.2: What is the history of the IOCCC website?
#### In the beginning of www.ioccc.org The long history of the [official IOCCC website](index.html) can be viewed at the [Internet Wayback Machine Wayback Machine](https://web.archive.org). One can [view several thousand snapshots showing how the IOCCC website has evolved](https://web.archive.org/web/20230000000000*/www.ioccc.org) going back as far as [1998 Dec 12 www.ioccc.org](https://web.archive.org/web/19981212030016/https://www.ioccc.org/). On 2020 Dec 31, the IOCCC source tree was moved to the [IOCCC winner repo](https://web.archive.org/web/20210101211346/https://www.ioccc.org/) on [GitHub](https://github.com). From this point on, the [official IOCCC web site](index.html) became a [GitHub Pages](https://pages.github.com) website. #### 2020 Dec 28 bzip2 compressed tarball archive Furthermore, a bzip2 compressed tarball containing the released IOCCC entry source code may be found under the [archive/historic](archive/historic/index.html) directory. The file [archive-all.tar.bz2](archive/historic/archive-all.tar.bz2) contains all years and the individual years are in the form `archive/historic/archive-YYYY.tar.bz2`. These files were obtained from the [Internet Wayback Machine](https://web.archive.org) from the [snapshot of the website on 2020 Dec 28](https://web.archive.org/web/20201228005211/https://www.ioccc.org/). See [archive/historic/index.html](archive/historic/index.html) for details about these bzip2 compressed tarballs. #### 2022 Dec 29 Official IOCCC winner repo The [Official IOCCC winner repo](https://github.com/ioccc-src/winner) was [created on 2020 Dec 29](https://github.com/ioccc-src/winner/commit/28efc67f5dd692a3544708bf7fa26286adb82dfb). #### 2020 Dec 30 IOCCC content uploaded to GitHub An [IOCCC judge](judges.html) formed a local directory [git](https://git-scm.com) repo on **Tue Dec 29 23:48:30 2020 -0800** via [commit 28efc67f5dd692a3544708bf7fa26286adb82dfb](https://github.com/ioccc-src/winner/commit/28efc67f5dd692a3544708bf7fa26286adb82dfb) and then on **Wed Dec 30 16:57:03 2020 -0800** added a preview of 1984-2019 via [commit c0663537cb88d39b74285a930ff1a668c6d5968b](https://github.com/ioccc-src/winner/commit/c0663537cb88d39b74285a930ff1a668c6d5968b). On 2020 Dec 30, with [commit c0663537cb88d39b74285a930ff1a668c6d5968b](https://github.com/ioccc-src/winner/commit/c0663537cb88d39b74285a930ff1a668c6d5968b), the [official IOCCC website of 2022 Dec 29](https://web.archive.org/web/20221231001721/https://www.ioccc.org/) was uploaded into the [Official IOCCC winner repo](https://github.com/ioccc-src/winner). #### 2020 IOCCC winning entries released using git via GitHub The [winning entries](https://github.com/ioccc-src/winner/commit/9d61fc0fb4a3245afb1435458cfb597fad0e8e6a) of the [IOCCC 2020](years.html#2020), after a far too long of a delay (due in part to a [former IOCCC judge whose resignation was noted on 2021 Jan 04](https://github.com/ioccc-src/winner/commit/c94fc84c35dc83e3eb9900720b95917a15c27afe) commit) from their initial [2020 Jul 25 announcement](https://web.archive.org/web/20200726232505/http://www.ioccc.org:80/index.html), were added by an [IOCCC judge](judges.html) to their local [git](https://git-scm.com) repository and then were merged into the [Official IOCCC winner repo on 2020 Dec 31](https://github.com/ioccc-src/winner/commit/b1638ff0012964d79ab1c44aa815d3f824f35b6c). These [2020 IOCCC winning entries](years.html#2020), as shown in the [Internet Wayback Machine](https://web.archive.org) [snapshot of 2021 Jan 02](https://web.archive.org/web/20210102042216/www.ioccc.org/years.html) were the first IOCCC entries to have been released via [git](https://git-scm.com) and [GitHub](https://github.com). #### 2020 Dec 30 thru 2024 Dec 28 - Work on the temp-test-ioccc GitHub repo Starting on [2020 Dec 30](https://github.com/ioccc-src/winner/commit/2f20ae8451ada03f4601ac727d10e1d8630861a8) edits to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner) began. The local [git](https://git-scm.com) repository of an [IOCCC judge](judges.html) was [edited starting Wed Dec 30 16:57:03 2020 -0800](https://github.com/ioccc-src/winner/commit/c0663537cb88d39b74285a930ff1a668c6d5968b) and was occasionally committed to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner). The [first accepted pull request](https://github.com/ioccc-src/winner/pull/2) to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner) was made by [Yusuke Endoh](authors.html#Yusuke_Endoh) on [2021 Jan 5](https://github.com/ioccc-src/winner/commit/84c62c4cbf56ac1351ea91e5019f51103615fda2). Between [Wed Dec 30 16:57:03 2020 -0800](https://github.com/ioccc-src/winner/commit/c0663537cb88d39b74285a930ff1a668c6d5968b) and [Sat Jan 29 21:56:53 2022 -0800](https://github.com/ioccc-src/winner/commit/098a3e7e04d43e480ecc4b5482c83274e1434002), an [IOCCC judge](judges.html) made edits to their local repository with occasional pushes to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner) and the [Official www.ioccc.org website](index.html). After that time and until the **Great Fork Merge**, very few changes were made to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner) and the [Official www.ioccc.org website](index.html) most of which were news updates. While the [temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc) has history going back to [2020 Dec 29](https://github.com/ioccc-src/temp-test-ioccc/commit/28efc67f5dd692a3544708bf7fa26286adb82dfb), the repo was forked on **Sun Sep 18 17:30:00 2022 -0700**. The first [push into the temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc/commit/edbc3089e1b755d85a020af7975bbc7df3737a5f) occurred on Sun Sep 18 11:15:49 2022 -0700, by [Cody Boone Ferguson](authors.html#Cody_Boone_Ferguson). At this same time, the [temp-test-ioccc website](https://ioccc-src.github.io/temp-test-ioccc/) went live. Edits were made by an [IOCCC judge](judges.html) to their local [git](https://git-scm.com) repository and [were pushed into the temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc/commit/2f20ae8451ada03f4601ac727d10e1d8630861a8) and to the [temp-test-ioccc website](https://ioccc-src.github.io/temp-test-ioccc/). The [first accepted pull request](https://github.com/ioccc-src/temp-test-ioccc/pull/15) made directly to the [temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc) on [Wed Feb 22 05:44:55 2023 -0800 with commit 11bb36ac8ce790f32a9a3e5d2131ee12820fb8ec](https://github.com/ioccc-src/temp-test-ioccc/commit/11bb36ac8ce790f32a9a3e5d2131ee12820fb8ec) by [Cody Boone Ferguson](authors.html#Cody_Boone_Ferguson). A [decision was made by the IOCCC](https://github.com/ioccc-src/temp-test-ioccc/discussions/1918) to mostly use frequent commits to individual components of the IOCCC, rather than to use occasional site wide massive updates in order to improve the tractability of changes made to components of the IOCCC such as IOCCC entries although occasionally site wide updates were performed in order to address an issue common to many IOCCC entries. And while some people prefer infrequent updates to a repo the [IOCCC judges](judges.html) believe the ability to trace changes with commit messages is important. Changes to the IOCCC content included things such as: * Moving IOCCC entries into their own separate directories. * Establishing a detailed manifest for IOCCC winning entries. * Fixing lots and lots of typos. * Fixing Makefiles and code to allow for nearly all winning entries to be compiled with/in modern systems. * Fixing Makefiles and code to allow for nearly all winning entries to run with/in modern systems. * Reworking the Makefiles to use a consistent set of rules. * Reworking the Makefiles specific to the gcc and clang C compilers. * Replacing the various hint files with a index.html markdown (from README.md files) that is more consistent across IOCCC years. * Generating HTML content from markdown files and JSON data files via a [set of tools and scripts](bin/index.html). * Setting up a system whereby authors of IOCCC entries may update their own contact information via a [GitHub pull request](https://github.com/ioccc-src/winner/pulls). * Setting up to generate the top level [years.html](years.html) file via the [gen-years.sh](%%REPO_URL%%/bin/gen-years.sh) tool. * Setting up to generate the top level [authors.html file](authors.html), renamed from `winners.html`, via the [gen-authors.sh](%%REPO_URL%%/bin/gen-authors.sh) tool. * Making use of a new and improved [IOCCC CSS](%%REPO_URL%%/ioccc.css) for website consistency * Etc.
#### 2024 Dec 28 The Great Fork Merge
As of 2024 Dec 28 [temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc) there were [6169 commits ahead](https://github.com/ioccc-src/winner/compare/master...ioccc-src:temp-test-ioccc:master) of the [IOCCC winner repo](https://github.com/ioccc-src/winner). On 2024 Dec 28, the temporary repo was merged back into the [IOCCC winner repo](https://github.com/ioccc-src/winner) resulting in many, many substantial improvements to the [official IOCCC website](index.html). In particular, the **Great Fork Merge** was commit 0b6326676dc0d3c12cf3ba47958244fc34b4f32f and took place on 2024 Dec 29, a total span of **833 days** ‼️ For details see [GH-commit/0b6326676dc0d3c12cf3ba47958244fc34b4f32f](https://github.com/ioccc-src/temp-test-ioccc/commit/0b6326676dc0d3c12cf3ba47958244fc34b4f32f) and the [Pull Request 24 in the winner repo](https://github.com/ioccc-src/winner/pull/24) that it produced. The **Great Fork Merge** _changed 5,157 files_ with _843,045 additions_ and _137,758 deletions_, in _6,169 commits_ ‼️ Jump to: [top](#)
### Q 11.3: How has the Rule 2 size restrictions rule changed over the years?
The IOCCC size rule has changed over the years. In later years, Rule 2 was split into two parts. These two parts of Rule 2 are: * Rule 2a: Overall size limit of "prog.c" * Rule 2b: Size of "prog.c", w/o counting certain types of characters
#### IOCCC 1984-1985
**NOTE**: The size rule was actually rule 1. * Rule 2a: 512 * Rule 2b: n/a
#### IOCCC 1986-1987
**NOTE**: The size rule was actually rule 1. * Rule 2a: 1024 * Rule 2b: n/a
#### IOCCC 1988-1991
**NOTE**: The size rule was actually rule 1. * Rule 2a: 1536 * Rule 2b: n/a
#### IOCCC 1992-2000
* Rule 2a: 3217 * Rule 2b: 1536
#### IOCCC: 2001-2012
* Rule 2a: 4096 * Rule 2b: 2048
#### IOCCC 2013-2020
* Rule 2a: 4096 * Rule 2b: 2053
#### IOCCC 2024-date
* Rule 2a: 4993 * Rule 2b: 2503
#### Size rule slow to change
As you can read above, the Size rule is slow to change. Given how long the [IOCCC 2013-2020](#size_rule2013-2020) size rule lasted, one might expect the [IOCCC 2024-date](#size_rule2024-xxxx) size rule to last well into the 2030's. Jump to: [top](#)
### Q 11.4: What is the **Great Fork Merge**?
The **Great Fork Merge** was when thousands of changes that had been applied to the [temp-test-ioccc repo](https://github.com/ioccc-src/temp-test-ioccc) was applied to the [Official IOCCC winner repo](https://github.com/ioccc-src/winner) causing the [Official IOCCC website](index.html) to be updated into its present form. See the FAQ on "[Great Fork Merge Date](#great_fork_merge_date)" for more information and stats. Jump to: [top](#)
### Q 11.5: What is an IOCCC BOF?
The term **IOCCC BOF** stood for **International Obfuscated C Code Contest Birds Of a Feather**. It was a special session held at the general [USENIX conference](https://www.usenix.org/conferences), usually immediately after the BSD BOF, where the winners of a new IOCCC were announced in the early years of the IOCCC. Jump to: [top](#)
### Q 11.6: I do not understand the IOCCC, can you explain it to me?
Please see the [About the IOCCC page](about.html) for more details. Jump to: [top](#)