Merge pull request #37 from justinhj/operation-modernize

Add CMake configuration and instructions

Author: justinhj

cpp/.clang-format .clang-formatcpp/.clang-format renamed to .clang-format

@@ -13,6 +13,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: make test
-      working-directory: ./cpp
-      run: make test
+    - name: Configure CMake
+      run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+    - name: Build
+      run: cmake --build build
+    - name: Test
+      working-directory: ./build
+      run: ./tests

.github/workflows/c-cpp.yml

@@ -3,3 +3,5 @@ cpp/8puzzle
 cpp/findpath
 cpp/minpathbucharest
 cpp/tests
+build/
+build-release

.gitignore

@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.10)
+project(astar-algorithm-cpp)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
+
+# Header-only library interface (optional but good practice)
+add_library(stlastar INTERFACE)
+target_include_directories(stlastar INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
+
+# Executables
+add_executable(8puzzle 8puzzle.cpp)
+target_link_libraries(8puzzle stlastar)
+
+add_executable(findpath findpath.cpp)
+target_link_libraries(findpath stlastar)
+
+add_executable(minpathbucharest min_path_to_Bucharest.cpp)
+target_link_libraries(minpathbucharest stlastar)
+
+# Tests
+enable_testing()
+add_executable(tests tests.cpp)
+target_link_libraries(tests stlastar)
+add_test(NAME tests COMMAND tests)

cpp/8puzzle.cpp 8puzzle.cppcpp/8puzzle.cpp renamed to 8puzzle.cpp

@@ -0,0 +1,92 @@
+# A* Algorithm C++ Implementation
+
+## Project Overview
+
+This project provides a clean, efficient, and header-only C++ implementation of the A* (A-Star) pathfinding algorithm. It is designed for high-performance applications like video games and includes an optional fixed-size memory allocator (`fsa.h`) to minimize memory fragmentation and allocation overhead.
+
+The core logic resides in `stlastar.h`, which uses C++ templates to work with any user-defined state class that satisfies the required interface.
+
+## Building and Running
+
+### Prerequisites
+*   C++ compiler supporting C++11 (e.g., `g++`, `clang++`).
+*   `make` utility.
+
+### Build Commands
+The project uses a `makefile` to manage builds.
+
+*   **Build All:**
+    ```bash
+    make
+    ```
+    This compiles the library examples and tests, producing the following executables:
+    *   `8puzzle`: Solves the 8-puzzle sliding tile game.
+    *   `findpath`: Finds a path on a simple grid map.
+    *   `minpathbucharest`: Solves the "classic" AI problem of finding the shortest path to Bucharest.
+    *   `tests`: Runs the unit tests.
+
+*   **Run Tests:**
+    ```bash
+    make test
+    ```
+
+*   **Clean Build:**
+    ```bash
+    make clean
+    ```
+
+### Running Examples
+*   **8-Puzzle:**
+    ```bash
+    ./8puzzle [board_string]
+    # Example: ./8puzzle 013824765
+    ```
+*   **Pathfinder:**
+    ```bash
+    ./findpath
+    ```
+
+## Development Conventions
+
+### Core Architecture
+*   **`stlastar.h`**: The main header file containing the `AStarSearch` class template. This is a header-only library; simply include this file in your project.
+*   **`fsa.h`**: A fixed-size block memory allocator used internally by `AStarSearch` to optimize node allocation. Can be toggled via `USE_FSA_MEMORY` in `stlastar.h`.
+
+### User State Interface
+To use the A* search, you must define a class (e.g., `MapSearchNode`) that represents a state in your search space. This class acts as a template argument to `AStarSearch` and **must** implement the following methods:
+
+```cpp
+class YourStateClass {
+public:
+    // Heuristic estimate of distance to goal (e.g., Manhattan distance, Euclidean distance)
+    float GoalDistanceEstimate(YourStateClass &nodeGoal);
+
+    // Returns true if this node is the goal
+    bool IsGoal(YourStateClass &nodeGoal);
+
+    // Generates successors and adds them to the search
+    // Implementation should call astarsearch->AddSuccessor(NewNode) for each valid move
+    bool GetSuccessors(AStarSearch<YourStateClass> *astarsearch, YourStateClass *parent_node);
+
+    // Cost of moving from this node to the successor
+    float GetCost(YourStateClass &successor);
+
+    // Returns true if this state is identical to rhs
+    bool IsSameState(YourStateClass &rhs);
+
+    // Returns a hash of the state (required for std::unordered_set)
+    size_t Hash();
+};
+```
+
+### Usage Pattern
+1.  Instantiate `AStarSearch<YourStateClass> astarsearch;`.
+2.  Create start and goal states.
+3.  Call `astarsearch.SetStartAndGoalStates(start, goal)`.
+4.  Loop `astarsearch.SearchStep()` until the state is `SEARCH_STATE_SUCCEEDED` or `SEARCH_STATE_FAILED`.
+5.  Retrieve the path using `astarsearch.GetSolutionStart()`, `GetSolutionNext()`, etc.
+6.  Call `astarsearch.FreeSolutionNodes()` and `astarsearch.EnsureMemoryFreed()` to clean up.
+
+### Testing
+*   Tests are located in `tests.cpp`.
+*   Ensure all tests pass with `make test` before submitting changes.

CMakeLists.txt

@@ -54,21 +54,25 @@ If you wish to be added to the list of known products/educational projects using
 * Lighthouses AI contest https://github.com/marcan/lighthouses_aicontest
 * Self-Driving Car Engineer Nanodegree Program https://github.com/vanAken/CarND-Path-Planning-Project
 
-### Compilation
+### Building
 
-Enter the cpp folder and run make
+Generally you can just include the stlastar.h and, optionally, the fsa.h header files and use it directly. The build instructions below are purely for the test suite and example executables.
 
-#### Introduction
+#### Using CMake
 
-This implementation is intended to be simple to read yet fairly
-efficient. To build it you can compile, with any recent C++ compiler,
-the following files :
+Some examples:
 
-For 8-puzzle solver
+** Use make and make a debug build **
+    ```bash
+    cmake -S . -B builddebug -DCMAKE_BUILD_TYPE=debug
+    ```
 
-* 8puzzle.cpp
-* stlastar.h
-* optionally fsa.h
+** Use Ninja and make a Release build **
+    ```bash
+    cmake -S . -B ninjabuildrelease -DCMAKE_BUILD_TYPE=release
+    ```
+
+In both cases you can execute the build using `make -C [build folder]` or `ninja -C [build folder]`.
 
 #### Command line 
 
@@ -99,4 +103,4 @@ it if you hit an out of memory assert during the search.
 
 Compatibility notes:
 
-This version of the code requires any standards compliant C++ using std C++11
+This version of the code requires any standards compliant C++ using std C++11. To build it requires a minimum cmake version you can find in the `CMakeLists.txt` file.