Skip to content

Commit

Permalink
Merge pull request #101 from xexyl/chkentry
Browse files Browse the repository at this point in the history 
Update FAQ, guidelines and quick start
  • Loading branch information
@lcn2
lcn2 authored Feb 28, 2025
2 parents b36623b + 2199f31 commit 84997f6
Show file tree
Hide file tree
Showing 6 changed files with 324 additions and 236 deletions.
73 changes: 48 additions & 25 deletions faq.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@ <h2>Frequently Asked Questions</h2>

<!-- BEFORE: 1st line of markdown file: faq.md -->
<h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1>
<p>This is FAQ version <strong>28.2.10 2025-02-26</strong>.</p>
<p>This is FAQ version <strong>28.2.11 2025-02-27</strong>.</p>
<h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter_questions">Entering the IOCCC: the bare minimum you need to know</a></h2>
<ul>
<li><strong>Q 0.0</strong>: <a class="normal" href="#enter">How can I enter the IOCCC?</a></li>
Expand All @@ -434,7 +434,8 @@ <h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter
<li><strong>Q 0.1.1</strong>: <a class="normal" href="#about_mkiocccentry">What is <code>mkiocccentry(1)</code> in simple terms?</a></li>
<li><strong>Q 0.1.2</strong>: <a class="normal" href="#obtaining_mkiocccentry">How do I obtain the latest mkiocccentry toolkit?</a></li>
<li><strong>Q 0.1.3</strong>: <a class="normal" href="#compiling_mkiocccentry">How do I compile the mkiocccentry toolkit?</a></li>
<li><strong>Q 0.1.4</strong>: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a></li>
<li><strong>Q 0.1.4</strong>: <a class="normal" href="#install">How do I install mkiocccentry(1) and related tools?</a></li>
<li><strong>Q 0.1.5</strong>: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a></li>
</ul></li>
<li><strong>Q 0.2</strong>: <a class="normal" href="#platform">What platform should I assume for my submission?</a></li>
<li><strong>Q 0.3</strong>: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a></li>
Expand Down Expand Up @@ -480,6 +481,7 @@ <h2 id="the-mkiocccentry-toolkit-finer-details">3. <a href="#mkiocccentry_detail
<li><strong>Q 3.9</strong>: <a class="normal" href="#entry_id_faq">What is an <code>entry_id</code>?</a></li>
<li><strong>Q 3.10</strong>: <a class="normal" href="#entry_json">What is a <code>.entry.json</code> file and how is it used?</a></li>
<li><strong>Q 3.11</strong>: <a class="normal" href="#jparse">How can I validate any JSON document?</a></li>
<li><strong>Q 3.12</strong>: <a class="normal" href="#install">How can I install the <code>mkiocccentry(1)</code> and related tools?</a></li>
</ul>
<h2 id="compiling-ioccc-entries">4. <a href="#compiling">Compiling IOCCC entries</a></h2>
<ul>
Expand Down Expand Up @@ -680,17 +682,43 @@ <h4 id="q-0.1.3-how-do-i-compile-the-mkiocccentry-toolkit">Q 0.1.3: How do I com
<p>Once you’ve obtained the <strong>LATEST</strong> version (see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the latest mkiocccentry toolkit</a>”
to make sure of this), change to the <code>mkiocccentry</code> directory and then run:</p>
<pre><code> make clobber all test</code></pre>
<p>to compile all the tools and run the test-suite.</p>
<p>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:</p>
<pre><code> make clobber all</code></pre>
<p>to compile all the tools.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="install">
<h3 id="q-0.1.4-how-do-i-install-mkiocccentry1-and-related-tools">Q 0.1.4: How do I install mkiocccentry(1) and related tools?</h3>
</div>
<p>After obtaining the toolkit (see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the latest mkiocccentry toolkit</a>”)
and compiling the tools (see the
FAQ on “<a href="#compiling_mkiocccentry">compiling mkiocccentry</a>”
above) run as either <code>sudo(8)</code> or root <code>make install</code>:</p>
<pre><code> # if you use sudo(8):
sudo make install

# as root:
make install</code></pre>
<p>If everything goes well you should be able to run <code>mkiocccentry(1)</code>,
<code>txzchk(1)</code>, <code>chkentry(1)</code> 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.</p>
<p>Some tools like <code>bug_report.sh</code> and <code>hostchk.sh</code> are not meant to be installed
and will not work from any directory, however.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="using_mkiocccentry">
<h4 id="q-0.1.4-how-do-i-use-mkiocccentry">Q 0.1.4: How do I use mkiocccentry?</h4>
<h4 id="q-0.1.5-how-do-i-use-mkiocccentry">Q 0.1.5: How do I use mkiocccentry?</h4>
</div>
<p>Once you have registered, you will need to package your entry with the
<code>mkiocccentry</code> tool. If you have not already obtained the toolkit, see the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the mkiocccentry toolkit</a>”
and the
FAQ on “<a href="#obtaining_mkiocccentry">obtaining the most recent mkiocccentry
toolkit</a>”,
the
FAQ on “<a href="#compiling_mkiocccentry">compiling mkiocccentry</a>”
and the
FAQ on “<a href="#installing">installing the mkiocccentry tools</a>”
if you have not already done so.</p>
<p>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,
Expand All @@ -709,15 +737,10 @@ <h4 id="q-0.1.4-how-do-i-use-mkiocccentry">Q 0.1.4: How do I use mkiocccentry?</
particular <a href="next/rules.html#rule17">Rule 17</a>.</p>
<p><strong>IMPORTANT NOTE</strong>: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
are required like <code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fnamchk(1)</code>. But even if you
have installed them but some tools are out of date (in the install path) it will
cause problems. Additionally, if you do not have the most recent version when
submitting a tarball it will be rejected for not having the right versions of
the tools. This is why you <strong>MUST</strong> make sure you have the most recent version
of all the tools and you either run it from the repo directory itself OR you
install them (<code>make install</code> as via <code>sudo</code> or as root). We recommend you install
the tools but if you wish to run it from the repo directory you may.</p>
installed the tools (and we <strong>STRONGLY</strong> recommend you <strong>do</strong> install them),
then you will have to specify the options for the tools that are required like
<code>chkentry(1)</code>, <code>txzchk(1)</code> and <code>fnamchk(1)</code>. And remember to make sure you have
the latest version so you do not violate <a href="next/rules.html#rule17">Rule 17</a>.</p>
<p>If the <strong><em>subdirectory</em> in the <em>work directory</em></strong> (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 (<strong>NOT</strong> the subdirectory), as it needs to be
Expand Down Expand Up @@ -1741,16 +1764,14 @@ <h3 id="q-3.2-what-is-the-fnamchk-tool">Q 3.2: What is the <code>fnamchk</code>
FAQ on “<a href="#txzchk">validating your submission tarball</a>”
for more information.</p>
<p>Jump to: <a href="#">top</a></p>
<div id="validating_auth_info_json">
<div id="chkentry">
<h3 id="q-3.3-how-can-i-validate-my-submission-directory">Q 3.3: How can I validate my submission directory?</h3>
</div>
</div>
<p>If you want to validate your submission directory manually, including but not
limited to the <code>.auth.json</code> or <code>.info.json</code> files, you should use <code>chkentry(1)</code>
limited to the <code>.auth.json</code> and <code>.info.json</code> files, you should use <code>chkentry(1)</code>
from the <a href="https://github.com/ioccc-src/mkiocccentry">mkiocccentry repo</a>.</p>
<p>The <code>chkentry(1)</code> tool runs a variety of checks on your submission directory,
including but not limited to, using the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3">jparse
including, but not limited to, using the <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3">jparse
API</a>
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
Expand All @@ -1768,12 +1789,14 @@ <h3 id="q-3.3-how-can-i-validate-my-submission-directory">Q 3.3: How can I valid
FAQ on “<a href="#info_json">.info.json</a>”
for more details on the two required and very important JSON files.</p>
<p>The <code>chkentry(1)</code> tool accepts a single arg, a directory that <strong>MUST</strong> have the
two JSON files, <code>.auth.json</code> and <code>.info.json</code>. (Okay there is an option to skip
files but this is for the judges <strong>ONLY</strong>; use of this option to validate your
submission puts you at a great risk of violating <a href="next/rules.html#rule17">Rule
17</a>!).</p>
<p>As an example, if your submission directory is <code>12345678-1234-4321-abcd-1234567890ab-0/</code> then you should run the
following command:</p>
two JSON files, <code>.auth.json</code> and <code>.info.json</code> as well as the <code>prog.c</code>,
<code>Makefile</code> and <code>remarks.md</code> files along with all the other files listed in the
<code>.info.json</code> manifest. (Okay there is an option to skip files but this is for
the judges <strong>ONLY</strong>; use of this option to validate your submission puts you at
a great risk of violating <a href="next/rules.html#rule17">Rule 17</a>!).</p>
<p>As an example, if your submission directory is
<code>12345678-1234-4321-abcd-1234567890ab-0/</code> then you should run the following
command:</p>
<pre><code> chkentry 12345678-1234-4321-abcd-1234567890ab-0</code></pre>
<p>If there is a <a href="https://www.json.org/json-en.html">JSON</a> issue detected by the
<code>jparse(3)</code> API (i.e. it is not valid JSON) it is an error and <code>chkentry(1)</code>
Expand Down
92 changes: 67 additions & 25 deletions faq.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# IOCCC FAQ Table of Contents

This is FAQ version **28.2.10 2025-02-26**.
This is FAQ version **28.2.11 2025-02-27**.


## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
Expand All @@ -9,7 +9,8 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 0.1.1**: <a class="normal" href="#about_mkiocccentry">What is `mkiocccentry(1)` in simple terms?</a>
- **Q 0.1.2**: <a class="normal" href="#obtaining_mkiocccentry">How do I obtain the latest mkiocccentry toolkit?</a>
- **Q 0.1.3**: <a class="normal" href="#compiling_mkiocccentry">How do I compile the mkiocccentry toolkit?</a>
- **Q 0.1.4**: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a>
- **Q 0.1.4**: <a class="normal" href="#install">How do I install mkiocccentry(1) and related tools?</a>
- **Q 0.1.5**: <a class="normal" href="#using_mkiocccentry">How do I use mkiocccentry?</a>
- **Q 0.2**: <a class="normal" href="#platform">What platform should I assume for my submission?</a>
- **Q 0.3**: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a>
- **Q 0.4**: <a class="normal" href="#remarks">What should I put in the remarks.md file of my submission?</a>
Expand Down Expand Up @@ -54,6 +55,7 @@ This is FAQ version **28.2.10 2025-02-26**.
- **Q 3.9**: <a class="normal" href="#entry_id_faq">What is an `entry_id`?</a>
- **Q 3.10**: <a class="normal" href="#entry_json">What is a `.entry.json` file and how is it used?</a>
- **Q 3.11**: <a class="normal" href="#jparse">How can I validate any JSON document?</a>
- **Q 3.12**: <a class="normal" href="#install">How can I install the `mkiocccentry(1)` and related tools?</a>


## 4. [Compiling IOCCC entries](#compiling)
Expand Down Expand Up @@ -289,23 +291,66 @@ 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:

``` <!---sh-->
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:

``` <!---sh-->
make clobber all
```

to compile all the tools.

Jump to: [top](#)

<div id="install">
### Q 0.1.4: How do I install mkiocccentry(1) and related tools?
</div>

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`:



``` <!---sh-->
# 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)`, `chkentry(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.

Jump to: [top](#)


<div id="using_mkiocccentry">
#### Q 0.1.4: How do I use mkiocccentry?
#### Q 0.1.5: How do I use mkiocccentry?
</div>

Once you have registered, you will need to package your entry with the
`mkiocccentry` tool. If you have not already obtained the toolkit, see the
FAQ on "[obtaining the mkiocccentry toolkit](#obtaining_mkiocccentry)"
and 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
Expand All @@ -332,15 +377,10 @@ particular [Rule 17](next/rules.html#rule17).

**IMPORTANT NOTE**: if you run the program outside the repo directory
(specifying the absolute or relative path to the tool) and you have not
installed the tools then you will have to specify the options for the tools that
are required like `chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. But even if you
have installed them but some tools are out of date (in the install path) it will
cause problems. Additionally, if you do not have the most recent version when
submitting a tarball it will be rejected for not having the right versions of
the tools. This is why you **MUST** make sure you have the most recent version
of all the tools and you either run it from the repo directory itself OR you
install them (`make install` as via `sudo` or as root). We recommend you install
the tools but if you wish to run it from the repo directory you may.
installed the tools (and we **STRONGLY** recommend you **do** install them),
then you will have to specify the options for the tools that are required like
`chkentry(1)`, `txzchk(1)` and `fnamchk(1)`. And remember to make sure you have
the latest version so you do not violate [Rule 17](next/rules.html#rule17).

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
Expand Down Expand Up @@ -1584,18 +1624,16 @@ for more information.
Jump to: [top](#)


<div id="validating_auth_info_json">
<div id="chkentry">
### Q 3.3: How can I validate my submission directory?
</div>
</div>

If you want to validate your submission directory manually, including but not
limited to the `.auth.json` or `.info.json` files, you should use `chkentry(1)`
limited to the `.auth.json` and `.info.json` files, you should use `chkentry(1)`
from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).

The `chkentry(1)` tool runs a variety of checks on your submission directory,
including but not limited to, using the [jparse
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
Expand All @@ -1616,13 +1654,15 @@ FAQ on "[.info.json](#info_json)"
for more details on the two required and very important JSON files.

The `chkentry(1)` tool accepts a single arg, a directory that **MUST** have the
two JSON files, `.auth.json` and `.info.json`. (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
17](next/rules.html#rule17)!).
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 17](next/rules.html#rule17)!).

As an example, if your submission directory is `12345678-1234-4321-abcd-1234567890ab-0/` then you should run the
following command:
As an example, if your submission directory is
`12345678-1234-4321-abcd-1234567890ab-0/` then you should run the following
command:


``` <!---sh-->
Expand Down Expand Up @@ -3557,6 +3597,7 @@ something along those lines.
Jump to: [top](#)



<div id="validating_json">
<div id="jparse">
### Q 3.11: How can I validate any JSON document?
Expand Down Expand Up @@ -3612,6 +3653,7 @@ as the two can be different at times.

Jump to: [top](#)


<hr style="width:50%;text-align:left;margin-left:0">
<hr style="width:50%;text-align:left;margin-left:0">

Expand Down
Loading

0 comments on commit 84997f6

Please sign in to comment.