I developed the Solver and the Generator on a Macintosh, but from the very start I wanted to be certain that they were portable to Windows-based PCs. That is why I chose Eclipse as an Integrated Development Environment rather than Apple’s Xcode. This appendix will show you how to set up and run the Solver and Generator.

Eclipse

This section is not a user’s guide for Eclipse, as you can find extensive documentation on the web, but setting it up on a PC running Windows is not entirely straightforward, and I would like to spare you at least some of the pain I had to go through!

To install Eclipse, you only need to go to http://eclipse.org/downloads/, download the package suitable for your operating system, and unzip it. At the moment of writing, the latest packages are eclipse-cpp-luna-SR1a-macosx-cocoa-x86_64.tar.gz for the Mac and eclipse-cpp-luna-SR1a-win32-x86_64.zip for the PC.

The installation of the Eclipse package itself is straightforward: all you need to do is expand the zip file you have downloaded and move the folder named “eclipse” to any convenient location. Any place will do but, to be on the safe side, I would choose a path that doesn’t contain any folder name with spaces. In the past, Eclipse couldn’t navigate through such names. Perhaps they have fixed the problem, but I haven’t checked whether it is so because it is not a big deal to be conservative in this case.

Eclipse is a Java application. Therefore, before you can execute it, you need to ensure that a Java Runtime Environment (JRE) is available on your system. Also, as the Eclipse package doesn’t include any compiler, it cannot do anything useful unless you also have a C compiler already installed on your system.

Once you have a JRE and a C compiler, to launch Eclipse you just double-click the icon of eclipse.app on a Mac or eclipse.exe on a PC.

With the MacOS (mine is Mavericks, 10.9.5), Eclipse is immediately ready to run, but under Windows on a PC, you need to do some preparatory work.

Setting Up Eclipse on a PC

First of all, you probably have to install a JRE. I say probably, because Microsoft meanwhile might have realized that a Windows PC should have a JRE or a JDK (Java Development Kit) already installed from the factory. To install Java on your PC is a simple operation: go to http://java.com and pick the appropriate JRE. Note that, unless you want to use Eclipse also to develop Java programs, you don’t need any development kit. The JRE will suffice.

I tested the Solver and the Generator on a system with Windows 7 Enterprise. It did have a C compiler installed, but I preferred to install GNU C (call me paranoid if you like!). To do so, point your web browser to the URL http://sourceforge.net/projects/mingw/files/, click the link marked “Automated MinGW Installer” and then, when you see the new page, click the link that starts with “Download.” When I did it, the link was named “Download mingw-get-setup.exe (86.5 KB),” but the name might have changed by the time you are reading this page.

MinGW means “Minimalist GNU for Windows,” which SourceForge describes as “A native Windows port of the GNU Compiler Collection (GCC), with freely distributable import libraries and header files for building native Windows applications; includes extensions to the MSVC runtime to support C99 functionality” (MSVC stands for “Microsoft Visual C”).

The installer asks you where you would like the program to be installed and then, after downloading several files, displays the MinGW Installation Manager’s window, which lets you choose what package you want to download. If you like, you can obviously download everything available, but to compile the Solver and the Generator, you only need the package for the basic MinGW installation, named mingw32-base.

After selecting the package, you click the item “Apply Changes” of the “Installation” menu and confirm it by clicking the button “Apply” in the dialog that pops up.

Once the Installation Manager is done with the downloading of files (it will take a while), go back to the “Installation” menu and click the item “Update Catalogue.”

You need the support of the C99 standard because it lets you define control variables of for-loops within the for statements, as in the following example:

for (int k = 0; k < 9; k++) {

This is a standard feature of Java that I find very good, and I almost always use this format in my coding, but it was not present in the C ANSI standard of 1990, which is the default for the GNU C compiler.

Fortunately, it was introduced into the ANSI standard of 1999 (hence the term “C99”).

Although C99 is included in the basic MinGW distribution, you have to configure Eclipse to use it. Once you have created the Solver and Generator projects (I’m jumping ahead of myself here), you can configure them to use C99 by opening the projects’ properties dialogue and adding the option -std=c99 to the compiler by selecting Settings GCC C Compiler Miscellaneous and adding the C99 option to the Other flags field, as shown in Figure A-1.

I like to encapsulate variables within limited scopes, and by defining the control variable within the for-statement, I achieve that the variable is invisible outside the loop. I could have achieved an equivalent result by adding a pair of braces, as in the following example:

{
  int k;
  for (k = 0; k < 9; k++) {
    ...
    } // for (k...
  }

but I find it ugly and cumbersome, as each for-loop would add two levels of indentation instead of one.

After you have installed the C compiler, you still have to install another package. Without it, you would not be able to work because you would keep getting the following error message every time you tried to run a Sudoku program:

12:03:04 **** Clean-only build of configuration Debug for project Generator ****
rm -rf src/inconsistent_unit.o src/display_string.d [GZ: rest omitted]
Cannot run program "rm": Launching failed

The message is caused by Eclipse attempting to execute the Unix command rm, which Windows doesn’t recognize. To solve this problem, go to

http://sourceforge.net/projects/gnuwin32/files/coreutils/5.3.0/coreutils-5.3.0.exe/download

and download the GNU coreutils in the form of an executable (EXE) file. If you don’t change any default while executing the EXE, the GNU utilities will be installed in C:Program Files (x86)GnuWin32in. To make them available to Eclipse, you will then need to add that path to the system variable Path.

In case you are not sure how to modify the Path, here is what you need to do: open the Control Panel System, click the link “Advanced system setting” and then the “Environment Variables” button. Scroll through the “System variables” until you see “Path,” select it, and click the “Edit” button. After that, move the cursor to the extreme left of the field “Variable value,” insert the new path, type a semicolon to keep it separate from the paths already there, and keep clicking the “OK” button until you are out of the control panel (see Figure A-2).

Coding Style

Eclipse lets you choose many options concerning the formatting of the source code. To configure Eclipse with your own style (i.e., with your own Formatter Profile), open the project properties of any project, select C/C++ General Formatter and click the link Configure Workspace Settings. This opens up the Formatter dialogue that lets you define a style for all your projects. Click the New button and you will see what is shown in Figure A-3.

After choosing a name for your style and clicking OK, you will get access to a series of options to modify it while leaving the predefined profiles unchanged. My style, which I have used throughout this book, differs from the K&R (see Appendix B for definition) style in only two things: two spaces of indentation instead of tabs equivalent to four spaces and indenting the closing braces, so that blocks “hang” from their first lines like flags.

if (condition) {
  whatever();
  }
else {
  something_else();
  }

My style makes the block statements easier to identify when looking at the code. Besides, the closing braces belong to the block statements and should therefore be indented. This is apparent if you replace the block statements with simple statements, as in the following example:

if (condition)
  whatever();
else
  something_else();

Why should the indentation change if you replace a single statement with a block statement?

In any case, as Eclipse doesn’t let me indent the closing braces, I systematically type two additional spaces before them. Obviously, you are welcome to reformat my source however you like!

Setting Up the Solver and the Generator

In this section, I explain how to set up the Solver, but almost everything I say will also apply to the Generator, the only difference between the two applications being that the Generator doesn’t need an input string.

The simplest way to create Eclipse projects for the Solver and the Generator is to position the cursor on the Project Explorer’s sidebar, right-click, select New, and then C Project. If you do so, you will see the dialog shown in Figure A-4.

Select Hello World ANSI C Project as shown, write Solver as the project name, select MinGW GCC as the toolchain, and click Finish. A folder named Solver will appear in the Project Explorer sidebar. Copy all the Solver source files attached to this book to the subfolder Solver/src/ of the Eclipse’s workspace folder. Then, within Eclipse, position the cursor on the Solver folder within the Project Explorer sidebar, right-click, and select Refresh. Open the src folder within the project Solver, which now contains all the sources of the Sudoku Solver, and delete Solver.c by right-clicking on it as shown in Figure A-5.

You can now build the Solver, but you are not yet ready to launch it. Open the src subfolder of the project and double-click sudoku_solver.c to open the Solver’s main module. Check that USE_FILE is not set. If you find that there is a #define USE_FILE, change it to something like #define USE_FILE_NO (or whatever else you like). This will ensure that the Solver expects a single Sudoku string as the first input argument, rather than reading several strings from the disk. Also check that the global variable silent is set to FALSE, so that the Solver sends log entries to Eclipse’s console.

If you right-click the project folder that you see in Eclipse’s Project Explorer sidebar, select Run As, and then Local C/C++ Application, you will get in the console the following error message: You need to provide a Sudoku string. Right! You have to pass a Sudoku string to the Solver as an argument!

To do so, click Eclipse’s Run menu and select the item Run Configurations. When the run configurations’ dialogue appears, click the tab marked (x)= Arguments, paste or type the Sudoku string of a puzzle into the text area marked Program arguments, click Apply, and then Run (see Figure A-6).

The Solver’s log will scroll up in the Console pane and stop with something similar to what you see in Listing A-1.

Listing A-1. The Solver Log

sudoku: the final grid contains 81 solved cells
     0   1   2    3   4   5    6   7   8
  ++===+===+===++===+===+===++===+===+===++
  ||   |   |   ||   |   |   ||   |   |   ||
0 ||(6)|(3)|(9)||(4)|(7)|(8)||(2)|(5)|(1)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
1 ||(4)|(5)|(8)||(3)|(1)|(2)||(9)|(6)|(7)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
2 ||(2)|(7)|(1)||(6)|(5)|(9)||(8)|(4)|(3)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++===+===+===++===+===+===++===+===+===++
  ||   |   |   ||   |   |   ||   |   |   ||
3 ||(7)|(9)|(6)||(5)|(2)|(4)||(1)|(3)|(8)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
4 ||(3)|(1)|(2)||(8)|(6)|(7)||(5)|(9)|(4)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
5 ||(5)|(8)|(4)||(9)|(3)|(1)||(7)|(2)|(6)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++===+===+===++===+===+===++===+===+===++
  ||   |   |   ||   |   |   ||   |   |   ||
6 ||(9)|(4)|(7)||(2)|(8)|(6)||(3)|(1)|(5)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
7 ||(1)|(2)|(3)||(7)|(4)|(5)||(6)|(8)|(9)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++---+---+---++---+---+---++---+---+---++
  ||   |   |   ||   |   |   ||   |   |   ||
8 ||(8)|(6)|(5)||(1)|(9)|(3)||(4)|(7)|(2)||
  ||   |   |   ||   |   |   ||   |   |   ||
  ++===+===+===++===+===+===++===+===+===++
****** 639478251458312967271659843796524138312867594584931726947286315123745689865193472
Strategies used 13: 'unique-loop' 'naked-pair' 'box-line' 'lines-2' 'lines-3' 'Y-wing' 'Y-wing' 'XY-chain' 'unique-loop' 'naked-pair' 'naked-pair' 'box-line' 'Y-wing'

I chose a difficult puzzle for this example!