<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Freecell Solver "Hacking"-Related Issues</title>
<date>2018-10-24</date>
<author>
<personname>
<firstname>Shlomi</firstname>
<surname>Fish</surname>
</personname>
<email>shlomif@cpan.org</email>
</author>
<authorinitials>SF</authorinitials>
</info>
<section xml:id="benchmarking">
<title>Benchmarking a Freecell Solver Release</title>
<simpara>Requirements: perl-5.14.x or above, CMake, gcc, bash and a working
pthreads-devel package.</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Use the git version control system to clone the repository and get a working
copy.</simpara>
</listitem>
<listitem>
<simpara>Create a fresh build directory like
<literal>mkdir "$HOME"/progs/freecell/git/fc-solve/fc-solve/source/../build"</literal>
and cd to it.</simpara>
</listitem>
<listitem>
<simpara>Run <literal>../source/Tatzer -l fc_bench -l extra_speed</literal> (for a Freecell-only capable solver)
or <literal>../source/Tatzer -l bench</literal> (for a solver that can solve all supported
games). Also append these options:</simpara>
<orderedlist numeration="loweralpha">
<listitem>
<simpara><literal>--max-bench-threads-num=4</literal> , where 4 is the maximal
number of threads you&#8217;d like to run which is a function of the number of
processors/cores your computer has.</simpara>
</listitem>
<listitem>
<simpara><literal>--prefix=$HOME/opt/fc-solve</literal> for setting the installation prefix to
install to.</simpara>
</listitem>
</orderedlist>
</listitem>
<listitem>
<simpara>Type <literal>make</literal> to build everything.</simpara>
</listitem>
<listitem>
<simpara>Type <literal>make install</literal>.</simpara>
</listitem>
<listitem>
<simpara>Type <literal>export FCS_PGO_THEME="-l lg" ;  bash pgo.bash</literal> to prepare a GCC Profile-Guided Optimizations (PGO)
executable.</simpara>
</listitem>
<listitem>
<simpara>Then you can run a shell script like this one:</simpara>
<screen>num_threads=4 ; for t in $(seq 1 8) ; do sudo_renice bash -c "$(printf 'ARGS="--worker-step 16 $FCS_PGO_THEME" bash ../scripts/time-threads-num.bash %d %d' $num_threads $num_threads)" ; done</screen>
<simpara>Where sudo_renice is something like:</simpara>
<simpara><link xl:href="https://github.com/shlomif/shlomif-computer-settings/blob/master/shlomif-settings/home-bin-executables/bin/sudo_renice">https://github.com/shlomif/shlomif-computer-settings/blob/master/shlomif-settings/home-bin-executables/bin/sudo_renice</link></simpara>
</listitem>
<listitem>
<simpara>To see the results, you can use <literal>perl ../scripts/time-fcs.pl
DUMPS-<emphasis role="strong">/</emphasis></literal> and copy-and-paste the results to the Freecell Solver developers
with specifications of your computer that are as detailed as possible.</simpara>
</listitem>
</orderedlist>
</section>
<section xml:id="test_suite">
<title>Getting the test suite up and running</title>
<simpara>These are instruction how to get the test suite up and running:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Install the dependencies: Subversion, CMake (3.x or later only), make,
gcc, g\++, valgrind, perl5 (at least perl-5.14)</simpara>
<itemizedlist>
<listitem>
<simpara>On Debian:</simpara>
<screen>apt-get install subversion cmake make gcc g++ valgrind perl</screen>
</listitem>
<listitem>
<simpara>On Mageia:</simpara>
<screen>urpmi subversion cmake make gcc g++ valgrind perl perl-devel</screen>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>Install the dependencies of the test suite:</simpara>
<itemizedlist>
<listitem>
<simpara>Download <literal>local::lib</literal> from <link xl:href="https://metacpan.org/release/local-lib">https://metacpan.org/release/local-lib</link>
and follow the instructions to set it up.</simpara>
</listitem>
<listitem>
<simpara>Restart bash (no need to restart the computer, just open a new terminal
window).</simpara>
<screen>export PERL_MM_USE_DEFAULT=1
perl -Mlocal::lib -MCPAN -e 'install Task::FreecellSolver::Testing'</screen>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>Install the development headers of
libtap ( <link xl:href="https://www.shlomifish.org/open-source/projects/libtap/">https://www.shlomifish.org/open-source/projects/libtap/</link> or perhaps
<link xl:href="https://github.com/mpapierski/libtap">https://github.com/mpapierski/libtap</link> )</simpara>
<itemizedlist>
<listitem>
<simpara>On Mageia:</simpara>
<screen>urpmi libtap-devel</screen>
</listitem>
<listitem>
<simpara>On Debian:</simpara>
<screen>tar -xvf /home/shlomif/Desktop/tap-1.01.tar.gz
cd tap-1.01
./configure --prefix="$HOME/apps/libtap"
make CFLAGS+=-UHAVE_LIBPTHREAD
make install
# For gcc finding tap.h in the includes
echo 'export CPATH="$HOME/apps/libtap/include:$CPATH"' &gt;&gt; ~/.bashrc
# For CMake finding libtap.
echo 'export CMAKE_PREFIX_PATH="$HOME/apps/libtap:$CMAKE_PREFIX_PATH"' &gt;&gt; ~/.bashrc</screen>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>Check out the latest Freecell Solver sources:</simpara>
<screen>git clone https://github.com/shlomif/fc-solve</screen>
<simpara>(You can also use <link xl:href="http://bundler.caurea.org/">http://bundler.caurea.org/</link> ).</simpara>
</listitem>
<listitem>
<simpara><literal>$ cd fc-solve/fc-solve/source/</literal></simpara>
</listitem>
<listitem>
<simpara><literal>$ mkdir build ; cd build</literal></simpara>
</listitem>
<listitem>
<simpara>Configure the Freecell Solver build</simpara>
<screen>../Tatzer</screen>
</listitem>
<listitem>
<simpara>Build Freecell Solver:</simpara>
<screen>make</screen>
</listitem>
<listitem>
<simpara>Test Freecell Solver:</simpara>
<screen>make test</screen>
</listitem>
</orderedlist>
</section>
<section xml:id="split_fcc_fc_solver">
<title>Running the split_fcc_fc_solver</title>
<simpara>The split_fcc_fc_solver (where "FCC" is "fully-connected-components") is
an experimental solver whose design is documented in <link xl:href="../docs/split-fully-connected-components-based-solver-planning.txt">the planning document</link>
and in <link xl:href="../docs/fully-connected-components-based-solver-planning.txt">another one</link> .</simpara>
<simpara>To run it use in the bash shell, either <literal>bash ../scripts/split-fcc&#8212;&#8203;all-in-one.bash</literal> which roughly expands to:</simpara>
<screen>mkdir -p ../B
cd ../B
../source/Tatzer -l pdfs
make
. ../scripts/split-fcc-SOURCE-ME.bash
startup
depth_run 1
depth_run 2
depth_run 3
depth_run 4
# And so forth with consecutive indices</screen>
<simpara>Note that currently some of the runs fail only to succeed on a rerun (
a <link xl:href="https://en.wikipedia.org/wiki/Heisenbug">Heisenbug</link> ) - at least on
Shlomi Fish&#8217;s local system. If you can investigate why it happens and propose a
fix, we will appreciate it.</simpara>
</section>
<section xml:id="style_guidelines">
<title>Style Guidelines</title>
<simpara>Freecell Solver uses its own style (largely based on the Allman style:
<link xl:href="http://en.wikipedia.org/wiki/Indent_style#Allman_style">http://en.wikipedia.org/wiki/Indent_style#Allman_style</link> ),
based on the preferences of its primary author (Shlomi Fish). The style is
largely enforced by the "clang-format" formatter (using its 7.0.0 version
currently). Some guidelines for the style will be given here.</simpara>
<section xml:id="four-spaces">
<title>4 Spaces for Indentation</title>
<simpara>The Freecell Solver source code should be kept free of horizontal
tabs (\t, HT, \x09) and use spaces alone. Furthermore, there should be
a 4 wide space indentation inside blocks:</simpara>
<screen>if (COND())
{
    int i;

    printf("%s\n", "COND() is successful!");

    for (i=0 ; i &lt; 10 ; i++)
    {
        ...
    }
}</screen>
</section>
<section xml:id="curly-braces">
<title>Curly Braces Alignment</title>
<simpara>The opening curly brace of an if-statement or a for-statement should be
placed below the statement on the same level as the other line, and the
inner block indented by 4 spaces. A good example can be found in the previous
section. Here are some bad examples:</simpara>
<screen>if ( COND() ) {
    /* Bad because the opening brace is on the same line.
}</screen>
<screen>if ( COND() )
    {
    /* Bad because the left and right braces are indented along with
    the block. */
    printf(....)
    }</screen>
<screen>/* GNU Style - fear and loathing. */
if ( COND() )
  {
    printf(....)
  }</screen>
</section>
<section xml:id="comments-precede">
<title>Comments should precede the lines performing the action</title>
<simpara>Comments should come one line before the line that they explain:</simpara>
<screen>/* Check if it can be moved to something on the same stack */
for ( dc = 0 ; dc &lt; c-1 ; dc++ )
{
    .
    .
    .
}</screen>
<simpara><literal>TODO: Fill in</literal></simpara>
</section>
<section xml:id="one-line-clauses">
<title>One line clauses should be avoided</title>
<simpara>One should avoid one-line clauses inside the clauses of <literal>if</literal>, <literal>else</literal>,
<literal>elsif</literal>, <literal>while</literal>, etc. Instead one should wrap the single statements inside
blocks. This is to avoid common errors with extraneous semicolons:</simpara>
<screen>/* Bad: */
if (COND())
    printf ("%s\n", "Success!");

/* Good: */
if (COND())
{
    printf ("%s\n", "Success!");
}

/* Bad: */
while (COND())
    printf("%s\n", "I'm still running.");

/* Good: */
while (COND())
{
    printf("%s\n", "I'm still running.");
}</screen>
</section>
<section xml:id="id-naming">
<title>Identifier Naming Conventions</title>
<simpara>Here are some naming conventions for identifiers:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Please do not use capital letters (including not <literal>CamelCase</literal>) - use
all lowercase letters with words separated by underscores. Remember, C is
case sensitive.</simpara>
</listitem>
<listitem>
<simpara>Note, however, that comments should be phrased in proper English, with
proper Capitalization and distinction between uppercase and lowercase
letters. So should the rest of the Freecell Solver internal and external
documentation.</simpara>
</listitem>
<listitem>
<simpara>Some commonly used abbreviations:</simpara>
</listitem>
</orderedlist>
<screen>max - maximum
num - numbers
cols - columns
dest - destination
src - source
ds - dest stack
stack - usually the source stack
ptr - pointer
val - value
c - the card index/position within the column
befs - Best First Search (one of the types of searches used by Freecell Solver)
a_star - also refers to "befs" from historical reasons (should be converted
to "befs" in the non-external interface.)
dfs - Depth-First Search (one of the types of searches used by Freecell Solver)</screen>
</section>
<section xml:id="if-0">
<title>Don&#8217;t comment-out - use #if 0 to temporarily remove code</title>
<simpara>Code should not be commented-out using gigantic <literal>/* &#8230;&#8203; */</literal> comments. Instead,
it should be out-blocked using <literal>#if 0&#8230;&#8203;#endif</literal>.</simpara>
<simpara>In Perl code, one can use the following POD paradigm to remove a block of
code:</simpara>
<screen>=begin Removed

Removed code here.

=end Removed

=cut</screen>
</section>
</section>
</article>