<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<?asciidoc-toc?>
<?asciidoc-numbered?>

<article lang="en">
<articleinfo>
    <title>Freecell Solver "Hacking"-Related Issues</title>
    <date>2009-08-14</date>
    <author>
        <firstname>Shlomi</firstname>
        <surname>Fish</surname>
        <email>shlomif@cpan.org</email>
    </author>
    <authorinitials>SF</authorinitials>
<revhistory><revision><revnumber>$Id$</revnumber><date>2009-08-14</date><authorinitials>SF</authorinitials></revision></revhistory>
</articleinfo>
<section id="_benchmarking_a_freecell_solver_release">
<title>Benchmarking a Freecell Solver Release</title>
<simpara>Requirements: perl-5.8.x or above, CMake, gcc, bash and a working
pthreads-devel package.</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
Download the Freecell Solver .tar.bz2 archive from
<ulink url="http://fc-solve.shlomifish.org/">http://fc-solve.shlomifish.org/</ulink> .
</simpara>
</listitem>
<listitem>
<simpara>
Unpack and cd to the freecell-solver-* directory.
</simpara>
</listitem>
<listitem>
<simpara>
Run <literal>./Tatzer -l tt --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>
Type <literal>make</literal> to build everything.
</simpara>
</listitem>
<listitem>
<simpara>
Type <literal>make bench</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
You can use <literal>perl scripts/time-fcs.pl dump DUMPS/*</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 id="_getting_the_test_suite_up_and_running">
<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 (2.6.3 or later only), make,
gcc, g\++, valgrind, perl5 (at least perl-5.8.9, perl-5.10.0 or above is
recommended),
</simpara>
<simpara>+
* On Debian:</simpara>
<screen>apt-get install subversion cmake make gcc g++ valgrind perl</screen>
<itemizedlist>
<listitem>
<simpara>
On Mandriva:
</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 <ulink url="http://search.cpan.org/dist/local-lib/">http://search.cpan.org/dist/local-lib/</ulink>
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 ( <ulink url="http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap">http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap</ulink> ).
</simpara>
<itemizedlist>
<listitem>
<simpara>
On Mandriva:
</simpara>
<literallayout class="monospaced"># urpmi libtap-devel</literallayout>
</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>svn co https://code.google.com/p/fc-solve/ trunk</screen>
</listitem>
<listitem>
<simpara>
<literal>$ cd trunk/fc-solve/source/</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Configure the Freecell Solver build
</simpara>
<literallayout class="monospaced">$ ./Tatzer</literallayout>
</listitem>
<listitem>
<simpara>
Build Freecell Solver:
</simpara>
<literallayout class="monospaced">$ make</literallayout>
</listitem>
<listitem>
<simpara>
Test Freecell Solver:
</simpara>
<literallayout class="monospaced">$ make test</literallayout>
</listitem>
</orderedlist>
</section>
<section id="_style_guidelines">
<title>Style Guidelines</title>
<simpara>Freecell Solver uses its own style based on the preferences of its primary
author (Shlomi Fish). Some guidelines for the style will be given here.</simpara>
<section id="_4_spaces_for_indentation">
<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 id="_curly_braces_alignment">
<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 id="_comments_should_precede_the_lines_performing_the_action">
<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 id="_one_line_clauses_should_be_avoided">
<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 id="_identifier_naming_conventions">
<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 id="_don_8217_t_comment_out_use_if_0_to_temporarily_remove_code">
<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; */</literal> comments. Instead,
it should be out-blocked using <literal>#if 0&#8230;#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>