Skip to content

Latest commit

 

History

History
378 lines (257 loc) · 11.9 KB

FAQ.md

File metadata and controls

378 lines (257 loc) · 11.9 KB

Frequently Asked Questions about the mkiocccentry repo

This is FAQ version 28.0.2 2024-10-09.

Table of Contents

  1. Where can I download the mkiocccentry toolkit?

  2. How do I compile the mkiocccentry tools?

  3. How do I install the tools and is it required?

  4. What can I do if my system's tar(1) does not support the correct options?

  5. How can I learn more about how to use the tools?

  6. How do I report bugs or other issues?

  7. How can I help test this repo?

  8. Why do these tools sometimes use the incorrect IOCCC terms?

  9. How do I participate in the IOCCC?

  10. How do I uninstall the toolkit?

0. Where can I find the mkiocccentry toolkit?

The mkiocccentry tool source code is found in the mkiocccentry repo. If you have not already done so, you may download the source by using git clone:

git clone https://github.com/ioccc-src/mkiocccentry.git

If you don't have git you can instead download the zip file and then extract that file.

1. How do I compile the mkiocccentry tools?

After downloading the repo (making sure that if you downloaded the zip file that you unzip it first) move into the mkiocccentry directory:

cd mkiocccentry

and compile everything from scratch:

make clobber all

If all is well, you will find the mkiocccentry executable in your local directory. If something went wrong, see how do I report bugs or other issues?

NOTE: the toolkit uses an import of the dbg repo, the dyn_array repo and the jparse repo. Although you may download, compile and install those, this is NOT a requirement and they may in fact at some points be different from the respective copies. The Makefiles here will link in the libraries that are compiled here, and not any external libraries. Thus although these libraries are needed for the tools, you do not need to install them in your system.

2. How do I install the tools and is it required?

You do not need to install the code (see below) but we HIGHLY recommend that you do so. To do this first compile the tools (making sure you have pulled or downloaded the most recent release of the repo):

make all

Next, run as root or via sudo(8):

make install

from the top level directory.

Why install?

This is because otherwise you need to either run the tools from the repo directory itself, requiring that you pass in the paths to your workdir and topdir, OR that you use all the options to specify the path to the tools (see also below). To do that last part you would have to do something like this (for this assume that the tools are in ~/mkiocccentry):

~/mkiocccentry/mkiocccentry -T ~/mkiocccentry/txzchk -F ~/mkiocccentry/test_ioccc/fnamchk -C ~/mkiocccentry/chkentry workdir topdir

where workdir is where your submission tarball will be formed and topdir is the directory where your submission files are located. As you can see that is much more tedious and harder to do.

If on the other hand you were in the mkiocccentry directory itself you would have to specify the paths to the workdir and topdir: which would be less tedious, perhaps, than running the tool from outside the repo directory, but still not as helpful.

If however you installed them you can simply do:

mkiocccentry workdir topdir

IMPORTANT NOTE: IF you do install them make sure you have installed the most recent version of all tools! Otherwise if you don't use the right options (say that you pulled the most recent version but did not install them - you installed an older release) the tools found will be in the install location (also if you do not install to the default location you would have to specify the options to the tools)!

Now if you need to install to a directory that is NOT the default (/usr/local) you can do:

make PREFIX=/usr install

as either root or via sudo(8).

NOTE: if you wish to test things try:

make all test

3. What can I do if my system's tar(1) does not support the correct options?

If your tar does not support the -J option you can either use a system which does have such a tar or you can try downloading GNU Tar from the GNU website and after extracting it, compile it and then install it so that the tools may find it.

Some systems have a GNU tar that you can use. For instance FreeBSD has a gtar command so if necessary you can use that. Note that you'll have to specify in the tools (that require a correct tar) the -t tar option to make this work.

4. How can I learn more about how to use the tools?

Assuming you have downloaded and compiled the code you can get a quick reminder of command options and arguments by use of the -h option of any tool:

For instance:

./mkiocccentry -h
./iocccsize -h
./chksubmit -h
./txzchk -h
./soup/location -h
./test_ioccc/fnamchk -h

There are man pages that go into much more detail than the -h help modes. You may use the man(1) command to read the man pages without having to install them.

After compiling this code, various man pages are copied under the local man/ directory at the top of the source directory.

For example:

man man/man1/mkiocccentry.1
man man/man1/iocccsize.1
man man/man1/chksubmit.1
man man/man1/txzchk.1
man man/man1/location.1
man man/man1/fnamchk.1

There are many other man pages under the man/ directory for the curious to read, using a similar technique. Of course if you have installed the toolkit then you don't need to specify the path.

If all that fails to satisfy your curiosity, we recommend you "use the source, Luke!" as you may find the code in this repo reasonably unobfuscated and fairly well commented.

NOTE: there are other tools not listed above that are not an important part of participating in the contest, at least not directly; look at the man pages, the Makefiles or compiled tools (or source code) for more details.

5. How do I report bugs or other issues?

If you've run into a problem with the repo and you think it is a bug then you should report it as a bug, making sure to give as much information as possible.

To help us help you PLEASE run the following command from the top level mkiocccentry directory (in other words, if you have installed the toolkit you MUST still run this from the toolkit directory):

make bug_report

and then attach the bug report log (see below about the filename).

You may also run the bug_report.sh tool directly:

./bug_report.sh -v 1

The bug report filename is in the format: bug-report.$(date +%Y%m%d.%H%M%S).txt where:

  • %Y is the four digit year (e.g. 2024).

  • %m is the two digit month (01..12).

  • %d is the two digit day of the month (e.g. 31).

  • %H is the two digit hour of the day (00..23).

  • %M is the two digit minute of the hour of the day (00..59); and

  • %S is the two digit second of the minute (in the range 0..60).

The script that the make rule runs, bug_report.sh, will tell you the name of the file to upload.

NOTE: the script might report that there is no problem but that does not mean there is no bug; on the other hand even if it reports a problem it does not necessarily mean there is a bug but you can report it as a bug as we can hopefully help. Feel free to use your judgement in this matter but most likely unless it's a feature request the best one is a bug report.

On the other hand, see the SECURITY file if you have a security concern.

NOTE: the bug_report.sh script runs test_ioccc/hostchk.sh but you can run it directly if you wish:

./test_ioccc/hostchk.sh

Thank you for any and all help!

Please see the README file in the test_ioccc subdirectory for more details on what you can do to help us.

7. Why do these tools sometimes use incorrect IOCCC terms?

According to the Official IOCCC FAQ 6.9 this repo sometimes uses the wrong term. For example the name mkiocccentry(1) contains the name entry when the tool is dealing with a submission. So why don't we call the tool mkiocccsubmission and rename the this repo?

Because the name mkiocccentry(1) and this repo name was selected before decisions were made in regards to the IOCCC term entry. And besides, the name mkiocccentry(1) contains a fun pun. And renaming the repo and updating all the code and data files (of which there are many) is not worth the hassle.

If the inconsistency bothers you, think of the name mkiocccentry(1) as a hopeful sign that the submission it is processing might actually win the IOCCC and become a winning entry. :-) After all, some submissions do go on to become winners, so maybe yours will too. :-)

You may find inconsistent use of Author(s), Entry, and Submission in this repo as well. The above "excuse" for entry instead of submission is just an example.

We made an attempt to correct some of the inconsistent use of the terms Author(s), Entry, and Submission in this repo. If you DO find a situation where the inconsistency is causing a problem and/or confusion, please let us know in the way of a bug report or if you're sure that it's correct, a pull request that corrects the mistake or mistakes. Please note that if you do this you MUST run make prep or at least make test. Not doing this poses a great risk of causing problems.

Note, however, that there are many cases where the words entry and/or entries are actually correct: they would only be incorrect if they refer to an IOCCC submission that has not won. In other words if it refers to submission(s) won then it should be entry (or entries).

8. How do I participate in the IOCCC?

Please see the official IOCCC website FAQ and in particular the FAQ on "submitting", the FAQ on "Makefiles", the FAQ on "source code filename, the FAQ on "mkiocccentry, the Rules and the Guidelines.

Pay especial care to [Rule 17 Packaging]((https://www.ioccc.org/next/rules.html#rule-17---packaging)!

## 9. How do I uninstall the toolkit?

If you have installed the tools and you wish to uninstall them, you can do so from the top level repo directory by typing:

make uninstall

as either root or via sudo.

Remember that if you installed with a different PREFIX you will have to use that same PREFIX to successfully uninstall the programs, library and man pages. For instance if you installed with the PREFIX of /usr you would type instead:

make PREFIX=/usr uninstall

After this all the files installed should be removed. If this is not the case by some chance it is likely a bug and you may report it as a bug here.