Freecell Solver "Hacking"-Related Issues

Benchmarking a Freecell Solver Release

Requirements: perl-5.14.x or above, CMake, gcc, bash and a working pthreads-devel package.

Use the git version control system to clone the repository and get a working copy.
Create a fresh build directory like mkdir "$HOME"/progs/freecell/git/fc-solve/fc-solve/source/../build" and cd to it.
Run ../scripts/Tatzer -l fc_bench -l extra_speed (for a Freecell-only capable solver) or ../scripts/Tatzer -l bench (for a solver that can solve all supported games). Also append these options:
1. --max-bench-threads-num=4 , where 4 is the maximal number of threads you’d like to run which is a function of the number of processors/cores your computer has.
2. --prefix=$HOME/opt/fc-solve for setting the installation prefix to install to.
Type make to build everything.
Type make install.
Type export FCS_PGO_THEME="-l lg" ; bash pgo.bash to prepare a GCC Profile-Guided Optimizations (PGO) executable.
Then you can run a shell script like this one:
```
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
```
Where sudo_renice is something like:

https://github.com/shlomif/shlomif-computer-settings/blob/master/shlomif-settings/home-bin-executables/bin/sudo_renice
To see the results, you can use perl ../scripts/time-fcs.pl DUMPS-/ and copy-and-paste the results to the Freecell Solver developers with specifications of your computer that are as detailed as possible.

Getting the test suite up and running

These are instruction how to get the test suite up and running:

Install the dependencies: Subversion, CMake (3.x or later only), make, gcc, g\++, valgrind, perl5 (at least perl-5.14)
- On Debian:
  apt-get install subversion cmake make gcc g++ valgrind perl
- On Mageia:
  urpmi subversion cmake make gcc g++ valgrind perl perl-devel
Install the dependencies of the test suite:
- Download local::lib from https://metacpan.org/release/local-lib and follow the instructions to set it up.
- Restart bash (no need to restart the computer, just open a new terminal window).
  export PERL_MM_USE_DEFAULT=1 perl -Mlocal::lib -MCPAN -e 'install Task::FreecellSolver::Testing'
Install the development distribution of cmocka ( https://cmocka.org/ ).
- On Fedora/Mageia:
  urpmi 'pkgconfig(cmocka)'
- On Debian:
  apt-get install libcmocka-dev

Check out the latest Freecell Solver sources:

git clone https://github.com/shlomif/fc-solve

$ cd fc-solve/fc-solve/source/
$ mkdir build ; cd build
Configure the Freecell Solver build
```
../../scripts/Tatzer
```
Build Freecell Solver:
```
make
```
Test Freecell Solver:
```
make test
```

Running the split_fcc_fc_solver

The split_fcc_fc_solver (where "FCC" is "fully-connected-components") is an experimental solver whose design is documented in the planning document and in another one .

To run it use in the bash shell, either bash ../scripts/split-fcc—all-in-one.bash which roughly expands to:

mkdir -p ../B
cd ../B
../scripts/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

Note that currently some of the runs fail only to succeed on a rerun ( a Heisenbug ) - at least on Shlomi Fish’s local system. If you can investigate why it happens and propose a fix, we will appreciate it.

NOTE/Update: the problem apparently disappears if one sets the NUM_THREADS environment variable to 1 before calling the script (which makes the solver use only one worker thread). This may indicate that there is a multithreading issue.

NOTE/Update No. 2: the problem seems to have been fixed in this change-set.

Style Guidelines

Freecell Solver uses its own style (largely based on the Allman style: http://en.wikipedia.org/wiki/Indent_style#Allman_style ), 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.

4 Spaces for Indentation

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:

if (COND())
{
    int i;

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

    for (i=0 ; i < 10 ; i++)
    {
        ...
    }
}

Curly Braces Alignment

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:

if ( COND() ) {
    /* Bad because the opening brace is on the same line.
}

if ( COND() )
    {
    /* Bad because the left and right braces are indented along with
    the block. */
    printf(....)
    }

/* GNU Style - fear and loathing. */
if ( COND() )
  {
    printf(....)
  }

Comments should precede the lines performing the action

Comments should come one line before the line that they explain:

/* Check if it can be moved to something on the same stack */
for ( dc = 0 ; dc < c-1 ; dc++ )
{
    .
    .
    .
}

TODO: Fill in

One line clauses should be avoided

One should avoid one-line clauses inside the clauses of if, else, elsif, while, etc. Instead one should wrap the single statements inside blocks. This is to avoid common errors with extraneous semicolons:

/* 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.");
}

Identifier Naming Conventions

Here are some naming conventions for identifiers:

Please do not use capital letters (including not CamelCase) - use all lowercase letters with words separated by underscores. Remember, C is case sensitive.
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.
Some commonly used abbreviations:

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)

Don’t comment-out - use #if 0 to temporarily remove code

Code should not be commented-out using gigantic /* … */ comments. Instead, it should be out-blocked using #if 0…#endif.

In Perl code, one can use the following POD paradigm to remove a block of code:

=begin Removed

Removed code here.

=end Removed

=cut