From 095cc2101130f1510733d1d7b5dac614d0a3b2b4 Mon Sep 17 00:00:00 2001 From: sora <123005041+kazurem@users.noreply.github.com> Date: Tue, 9 Dec 2025 20:53:29 +0500 Subject: [PATCH 01/23] Adding .clang-format file --- .clang-format | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 .clang-format diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..c314114 --- /dev/null +++ b/.clang-format @@ -0,0 +1,288 @@ +--- +Language: Cpp +AccessModifierOffset: -2 +AlignAfterOpenBracket: Align +AlignArrayOfStructures: None +AlignConsecutiveAssignments: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: true +AlignConsecutiveBitFields: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: false +AlignConsecutiveDeclarations: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: true + AlignFunctionPointers: false + PadOperators: false +AlignConsecutiveMacros: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: false +AlignConsecutiveShortCaseStatements: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCaseArrows: false + AlignCaseColons: false +AlignConsecutiveTableGenBreakingDAGArgColons: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: false +AlignConsecutiveTableGenCondOperatorColons: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: false +AlignConsecutiveTableGenDefinitionColons: + Enabled: false + AcrossEmptyLines: false + AcrossComments: false + AlignCompound: false + AlignFunctionDeclarations: false + AlignFunctionPointers: false + PadOperators: false +AlignEscapedNewlines: Right +AlignOperands: Align +AlignTrailingComments: + Kind: Always + OverEmptyLines: 0 +AllowAllArgumentsOnNextLine: true +AllowAllParametersOfDeclarationOnNextLine: true +AllowBreakBeforeNoexceptSpecifier: Never +AllowShortBlocksOnASingleLine: Never +AllowShortCaseExpressionOnASingleLine: true +AllowShortCaseLabelsOnASingleLine: false +AllowShortCompoundRequirementOnASingleLine: true +AllowShortEnumsOnASingleLine: true +AllowShortFunctionsOnASingleLine: All +AllowShortIfStatementsOnASingleLine: Never +AllowShortLambdasOnASingleLine: All +AllowShortLoopsOnASingleLine: false +AllowShortNamespacesOnASingleLine: false +AlwaysBreakAfterDefinitionReturnType: None +AlwaysBreakBeforeMultilineStrings: false +AttributeMacros: + - __capability +BinPackArguments: true +BinPackParameters: BinPack +BitFieldColonSpacing: Both +BraceWrapping: + AfterCaseLabel: false + AfterClass: false + AfterControlStatement: Never + AfterEnum: false + AfterExternBlock: false + AfterFunction: false + AfterNamespace: false + AfterObjCDeclaration: false + AfterStruct: false + AfterUnion: false + BeforeCatch: false + BeforeElse: false + BeforeLambdaBody: false + BeforeWhile: false + IndentBraces: false + SplitEmptyFunction: true + SplitEmptyRecord: true + SplitEmptyNamespace: true +BreakAdjacentStringLiterals: true +BreakAfterAttributes: Leave +BreakAfterJavaFieldAnnotations: false +BreakAfterReturnType: None +BreakArrays: true +BreakBeforeBinaryOperators: None +BreakBeforeConceptDeclarations: Always +BreakBeforeBraces: Attach +BreakBeforeInlineASMColon: OnlyMultiline +BreakBeforeTernaryOperators: true +BreakBinaryOperations: Never +BreakConstructorInitializers: BeforeColon +BreakFunctionDefinitionParameters: false +BreakInheritanceList: BeforeColon +BreakStringLiterals: true +BreakTemplateDeclarations: MultiLine +ColumnLimit: 80 +CommentPragmas: '^ IWYU pragma:' +CompactNamespaces: false +ConstructorInitializerIndentWidth: 4 +ContinuationIndentWidth: 4 +Cpp11BracedListStyle: true +DerivePointerAlignment: false +DisableFormat: false +EmptyLineAfterAccessModifier: Never +EmptyLineBeforeAccessModifier: LogicalBlock +ExperimentalAutoDetectBinPacking: false +FixNamespaceComments: true +ForEachMacros: + - foreach + - Q_FOREACH + - BOOST_FOREACH +IfMacros: + - KJ_IF_MAYBE +IncludeBlocks: Preserve +IncludeCategories: + - Regex: '^"(llvm|llvm-c|clang|clang-c)/' + Priority: 2 + SortPriority: 0 + CaseSensitive: false + - Regex: '^(<|"(gtest|gmock|isl|json)/)' + Priority: 3 + SortPriority: 0 + CaseSensitive: false + - Regex: '.*' + Priority: 1 + SortPriority: 0 + CaseSensitive: false +IncludeIsMainRegex: '(Test)?$' +IncludeIsMainSourceRegex: '' +IndentAccessModifiers: false +IndentCaseBlocks: false +IndentCaseLabels: false +IndentExportBlock: true +IndentExternBlock: AfterExternBlock +IndentGotoLabels: true +IndentPPDirectives: None +IndentRequiresClause: true +IndentWidth: 2 +IndentWrappedFunctionNames: false +InsertBraces: false +InsertNewlineAtEOF: false +InsertTrailingCommas: None +IntegerLiteralSeparator: + Binary: 0 + BinaryMinDigits: 0 + Decimal: 0 + DecimalMinDigits: 0 + Hex: 0 + HexMinDigits: 0 +JavaScriptQuotes: Leave +JavaScriptWrapImports: true +KeepEmptyLines: + AtEndOfFile: false + AtStartOfBlock: true + AtStartOfFile: true +KeepFormFeed: false +LambdaBodyIndentation: Signature +LineEnding: DeriveLF +MacroBlockBegin: '' +MacroBlockEnd: '' +MainIncludeChar: Quote +MaxEmptyLinesToKeep: 1 +NamespaceIndentation: None +ObjCBinPackProtocolList: Auto +ObjCBlockIndentWidth: 2 +ObjCBreakBeforeNestedBlockParam: true +ObjCSpaceAfterProperty: false +ObjCSpaceBeforeProtocolList: true +PackConstructorInitializers: BinPack +PenaltyBreakAssignment: 2 +PenaltyBreakBeforeFirstCallParameter: 19 +PenaltyBreakBeforeMemberAccess: 150 +PenaltyBreakComment: 300 +PenaltyBreakFirstLessLess: 120 +PenaltyBreakOpenParenthesis: 0 +PenaltyBreakScopeResolution: 500 +PenaltyBreakString: 1000 +PenaltyBreakTemplateDeclaration: 10 +PenaltyExcessCharacter: 1000000 +PenaltyIndentedWhitespace: 0 +PenaltyReturnTypeOnItsOwnLine: 60 +PointerAlignment: Right +PPIndentWidth: -1 +QualifierAlignment: Leave +ReferenceAlignment: Pointer +ReflowComments: Always +RemoveBracesLLVM: false +RemoveEmptyLinesInUnwrappedLines: false +RemoveParentheses: Leave +RemoveSemicolon: false +RequiresClausePosition: OwnLine +RequiresExpressionIndentation: OuterScope +SeparateDefinitionBlocks: Leave +ShortNamespaceLines: 1 +SkipMacroDefinitionBody: false +SortIncludes: CaseSensitive +SortJavaStaticImport: Before +SortUsingDeclarations: LexicographicNumeric +SpaceAfterCStyleCast: false +SpaceAfterLogicalNot: false +SpaceAfterTemplateKeyword: true +SpaceAroundPointerQualifiers: Default +SpaceBeforeAssignmentOperators: true +SpaceBeforeCaseColon: false +SpaceBeforeCpp11BracedList: false +SpaceBeforeCtorInitializerColon: true +SpaceBeforeInheritanceColon: true +SpaceBeforeJsonColon: false +SpaceBeforeParens: ControlStatements +SpaceBeforeParensOptions: + AfterControlStatements: true + AfterForeachMacros: true + AfterFunctionDefinitionName: false + AfterFunctionDeclarationName: false + AfterIfMacros: true + AfterOverloadedOperator: false + AfterPlacementOperator: true + AfterRequiresInClause: false + AfterRequiresInExpression: false + BeforeNonEmptyParentheses: false +SpaceBeforeRangeBasedForLoopColon: true +SpaceBeforeSquareBrackets: false +SpaceInEmptyBlock: false +SpacesBeforeTrailingComments: 1 +SpacesInAngles: Never +SpacesInContainerLiterals: true +SpacesInLineCommentPrefix: + Minimum: 1 + Maximum: -1 +SpacesInParens: Never +SpacesInParensOptions: + ExceptDoubleParentheses: false + InCStyleCasts: false + InConditionalStatements: false + InEmptyParentheses: false + Other: false +SpacesInSquareBrackets: false +Standard: Latest +StatementAttributeLikeMacros: + - Q_EMIT +StatementMacros: + - Q_UNUSED + - QT_REQUIRE_VERSION +TableGenBreakInsideDAGArg: DontBreak +TabWidth: 8 +UseTab: Never +VerilogBreakBetweenInstancePorts: true +WhitespaceSensitiveMacros: + - BOOST_PP_STRINGIZE + - CF_SWIFT_NAME + - NS_SWIFT_NAME + - PP_STRINGIZE + - STRINGIZE +WrapNamespaceBodyWithEmptyLines: Leave +... + From decf4957af706a1000045088cee13ea0b4e56568 Mon Sep 17 00:00:00 2001 From: Mutahir <123005041+kazurem@users.noreply.github.com> Date: Tue, 9 Dec 2025 21:17:02 +0500 Subject: [PATCH 02/23] Create .gitignore with common build artifacts Add common file types to .gitignore to prevent tracking. --- .gitignore | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d4fb281 --- /dev/null +++ b/.gitignore @@ -0,0 +1,41 @@ +# Prerequisites +*.d + +# Compiled Object files +*.slo +*.lo +*.o +*.obj + +# Precompiled Headers +*.gch +*.pch + +# Linker files +*.ilk + +# Debugger Files +*.pdb + +# Compiled Dynamic libraries +*.so +*.dylib +*.dll + +# Fortran module files +*.mod +*.smod + +# Compiled Static libraries +*.lai +*.la +*.a +*.lib + +# Executables +*.exe +*.out +*.app + +# debug information files +*.dwo From 022770fe5dc7665f1f7aa7f16ce67094529e7cd2 Mon Sep 17 00:00:00 2001 From: sora <123005041+kazurem@users.noreply.github.com> Date: Tue, 9 Dec 2025 22:37:20 +0500 Subject: [PATCH 03/23] Creating basic CMakeLists.txt and file structure --- CMakeLists.txt | 22 ++++++++++++++++++++++ include/MazeGen.hpp | 8 ++++++++ src/Main.cpp | 9 +++++++++ src/MazeGen.cpp | 13 +++++++++++++ 4 files changed, 52 insertions(+) create mode 100644 CMakeLists.txt create mode 100644 include/MazeGen.hpp create mode 100644 src/Main.cpp create mode 100644 src/MazeGen.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..fcaca32 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,22 @@ +cmake_minimum_required(VERSION 3.10) + +project(MicroMouse-Simulator LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 23) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# --- Define Source Files --- +set(APP_SOURCES src/Main.cpp src/MazeGen.cpp) + +# --- Create the Executable Target --- +add_executable(mms ${APP_SOURCES}) + +# --- Configure Include Directories --- + +# Tell the compiler where to find header files. +# By setting this as PUBLIC, any other target that links against 'my_app' +# will also get this include path (though typically the executable isn't linked to). +target_include_directories(mms + PUBLIC + ${CMAKE_SOURCE_DIR}/include +) diff --git a/include/MazeGen.hpp b/include/MazeGen.hpp new file mode 100644 index 0000000..4567ccd --- /dev/null +++ b/include/MazeGen.hpp @@ -0,0 +1,8 @@ +#pragma once +#include +#include + +class MazeGen { +public: + std::string generate(size_t rows, size_t columns); +}; \ No newline at end of file diff --git a/src/Main.cpp b/src/Main.cpp new file mode 100644 index 0000000..1ee2173 --- /dev/null +++ b/src/Main.cpp @@ -0,0 +1,9 @@ +#include "MazeGen.hpp" +#include + +int main() { + MazeGen gen; + auto maze = gen.generate(5, 10); + std::cout << "Hello Maze!\n"; + std::cout << maze << "\n"; +} \ No newline at end of file diff --git a/src/MazeGen.cpp b/src/MazeGen.cpp new file mode 100644 index 0000000..f3a8be2 --- /dev/null +++ b/src/MazeGen.cpp @@ -0,0 +1,13 @@ +#include + +std::string MazeGen::generate(size_t rows, size_t columns) { + std::string maze = ""; + for (size_t row = 0; row < rows; row++) { + maze += "|"; + for (size_t column = 0; column < columns; column++) { + maze += "-"; + } + maze += "|\n"; + } + return maze; +} \ No newline at end of file From 51b1a444cbfb035453e43344d217e5bd12b312e3 Mon Sep 17 00:00:00 2001 From: sora <123005041+kazurem@users.noreply.github.com> Date: Wed, 10 Dec 2025 01:32:19 +0500 Subject: [PATCH 04/23] Adding testing functionality using GoogleTest --- .gitignore | 3 ++ CMakeLists.txt | 68 +++++++++++++++++++++++++++++++++++------- include/MazeGen.hpp | 2 ++ src/MazeGen.cpp | 4 ++- tests/CMakeLists.txt | 27 +++++++++++++++++ tests/MazeGen-Test.cpp | 4 +++ 6 files changed, 96 insertions(+), 12 deletions(-) create mode 100644 tests/CMakeLists.txt create mode 100644 tests/MazeGen-Test.cpp diff --git a/.gitignore b/.gitignore index d4fb281..581aa95 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +#Custom +build/ + # Prerequisites *.d diff --git a/CMakeLists.txt b/CMakeLists.txt index fcaca32..29ec7b4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,22 +1,68 @@ -cmake_minimum_required(VERSION 3.10) +# Specifies the minimum version of CMake required to process this file. +# Using a range (3.50..4.0) ensures compatibility with modern features. +cmake_minimum_required(VERSION 3.16..4.2) +# Defines the project name and enables the C++ compiler. project(MicroMouse-Simulator LANGUAGES CXX) -set(CMAKE_CXX_STANDARD 23) +# Sets the C++ standard for the entire project to C++17. +# This ensures consistency across all source files and compilers. +set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED True) -# --- Define Source Files --- -set(APP_SOURCES src/Main.cpp src/MazeGen.cpp) +# --- GoogleTest Integration (Conditional) --- -# --- Create the Executable Target --- -add_executable(mms ${APP_SOURCES}) +# This block executes only if the user configures CMake with -DBUILD_TESTING=ON. +if(BUILD_TESTING) + include(FetchContent) + FetchContent_Declare( + googletest + GIT_REPOSITORY https://github.com/google/googletest.git + # Use a specific stable commit or tag (like release-1.14.0) for reliability. + GIT_TAG 52eb8108c5bdec04579160ae17225d66034bd723 + # Recommended: Add DOWNLOAD_EXTRACT_TIMESTAMP TRUE for build robustness (CMP0135). + ) + + # Makes the googletest targets (GTest::gtest, GTest::gtest_main, etc.) available + # for linking in subsequent targets (like mms-test). + FetchContent_MakeAvailable(googletest) +endif() + +# --- Project Structure and Dependencies --- + +# Include the CTest module for test registration and management. +include(CTest) + +# Add the 'tests' subdirectory, which contains its own CMakeLists.txt file. +add_subdirectory(tests) + +# --- Core Logic Library Definition --- + +# Define the source files that contain the reusable application logic. +set(CORE_SOURCES src/MazeGen.cpp) -# --- Configure Include Directories --- +# Create a Static Library target. This bundles the core logic into a reusable +# library that can be linked by both the main executable and the test executable. +add_library(mms-core STATIC ${CORE_SOURCES}) -# Tell the compiler where to find header files. -# By setting this as PUBLIC, any other target that links against 'my_app' -# will also get this include path (though typically the executable isn't linked to). -target_include_directories(mms +# Configure Include Directories +# Set the project's header directory as PUBLIC for the 'mms-core' library. +target_include_directories(mms-core PUBLIC ${CMAKE_SOURCE_DIR}/include ) +# The PUBLIC keyword ensures that any target that links to 'mms-core' (like 'mms' +# and 'mms-test') automatically inherits this include path. + +# --- Main Executable Definition --- + +# Define the source file(s) for the application entry point. +set(APP_SOURCES src/Main.cpp) + +# Create the main executable target +add_executable(mms ${APP_SOURCES}) + +# Link the core logic library to the main executable. +# PRIVATE linkage means the executable uses the library internally, +# but downstream targets don't need to know about it (standard best practice). +target_link_libraries(mms PRIVATE mms-core) diff --git a/include/MazeGen.hpp b/include/MazeGen.hpp index 4567ccd..557bf25 100644 --- a/include/MazeGen.hpp +++ b/include/MazeGen.hpp @@ -1,8 +1,10 @@ #pragma once #include #include +#include class MazeGen { public: std::string generate(size_t rows, size_t columns); + static size_t exampleFunc(); }; \ No newline at end of file diff --git a/src/MazeGen.cpp b/src/MazeGen.cpp index f3a8be2..d002d13 100644 --- a/src/MazeGen.cpp +++ b/src/MazeGen.cpp @@ -10,4 +10,6 @@ std::string MazeGen::generate(size_t rows, size_t columns) { maze += "|\n"; } return maze; -} \ No newline at end of file +} + +size_t MazeGen::exampleFunc() { return 42; } \ No newline at end of file diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt new file mode 100644 index 0000000..03785ef --- /dev/null +++ b/tests/CMakeLists.txt @@ -0,0 +1,27 @@ +# the test executable and related targets are only built when the user configures CMake with +# -DBUILD_TESTING=ON (as defined in the root CMakeLists.txt and CTest module). +if(BUILD_TESTING) + + # Creates the binary file (e.g., mms-test.exe) that will run all unit tests. + add_executable(mms-test MazeGen-Test.cpp) + + # Connects the test executable to the necessary compiled code. + target_link_libraries(mms-test + PRIVATE + # Links to the GoogleTest main library, which provides the main() function + # to run the tests and the testing framework itself. + GTest::gtest_main + + # Links to your project's core logic library (defined in the root CMakeLists.txt). + # This is essential for calling the functions that we want test. + mms-core + ) + + # Includes GoogleTest-specific CMake macros. This is necessary for gtest_discover_tests. + include(GoogleTest) + + # Searches the compiled executable (mms-test) for all defined tests (using TEST/TEST_F macros) + # and registers them with CTest. This allows you to run tests using the 'ctest' command. + gtest_discover_tests(mms-test) + +endif() \ No newline at end of file diff --git a/tests/MazeGen-Test.cpp b/tests/MazeGen-Test.cpp new file mode 100644 index 0000000..f782917 --- /dev/null +++ b/tests/MazeGen-Test.cpp @@ -0,0 +1,4 @@ +#include "MazeGen.hpp" +#include + +TEST(TestTopic, TrivialEquality) { EXPECT_EQ(MazeGen::exampleFunc(), 42); } \ No newline at end of file From a18f9b837e1a115087fdc67d532ab8d8504f4ec9 Mon Sep 17 00:00:00 2001 From: Mutahir <123005041+kazurem@users.noreply.github.com> Date: Wed, 10 Dec 2025 02:51:45 +0500 Subject: [PATCH 05/23] Adding Build Instructions and Troubleshooting in README.md Added: 1. Table of Contents 2. Build Instructions for the project 3. Troubleshooting guide 4. Link to helpful resources --- README.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 211 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5f1ee1d..2baf7f4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,211 @@ -# MicroMouse-Simulator -Micromouse maze simulator with pathfinding algorithms and interactive visualization. +# MicroMouse Simulator + +A sophisticated micromouse maze simulator featuring pathfinding algorithms and interactive visualization. + +--- + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Quick Start](#quick-start) +- [Building the Project](#building-the-project) + - [Step 1: Clone the Repository](#step-1-clone-the-repository) + - [Step 2: Configure the Build](#step-2-configure-the-build) + - [Step 3: Compile the Project](#step-3-compile-the-project) +- [Running the Simulator](#running-the-simulator) +- [Testing](#testing) +- [Troubleshooting](#troubleshooting) + +--- + +## Prerequisites + +Before building, ensure you have: + +- **CMake** (version 3.16 or higher) +- **C++ Compiler** (GCC, Clang, MSVC, or MinGW) +- **Git** (for cloning the repository) +- **Build System** (Make, Ninja, or MSBuild) + +--- + +## Quick Start +```bash +# Clone the repository +git clone https://github.com/kr8457/MicroMouse-Simulator +cd MicroMouse-Simulator + +# Switch to development branch (recommended) +git checkout dev + +# Configure with testing enabled +cmake -B build -DBUILD_TESTING=ON + +# Build the project +cmake --build build + +# Run tests +ctest --test-dir build --output-on-failure +``` + +--- + +## Building the Project + +### Step 1: Clone the Repository + +Clone the project from GitHub: +```bash +git clone https://github.com/kr8457/MicroMouse-Simulator +``` + +> **Tip:** The latest features are on the `dev` branch: +> ```bash +> git checkout dev +> ``` + +Navigate to the project directory: +```bash +cd MicroMouse-Simulator +``` + +### Step 2: Configure the Build + +#### Basic Configuration + +For a standard build without testing: +```bash +cmake -B build +``` + +#### Configuration with Testing + +To enable GoogleTest for unit testing: +```bash +cmake -B build -DBUILD_TESTING=ON +``` + +This will automatically fetch and build GoogleTest from source, integrating it with the project. + +#### Choosing a Generator + +You can specify different CMake generators using the `-G` flag: +```bash +# For MinGW Makefiles +cmake -B build -G "MinGW Makefiles" + +# For Visual Studio 2022 +cmake -B build -G "Visual Studio 17 2022" + +# For Ninja +cmake -B build -G "Ninja" +``` + +**What are generators?** Generators produce build system configurations that tools like Make, Ninja, or MSBuild use to compile your project. + +> [!NOTE] +> If no generator is specified, CMake automatically selects the default for your platform. + +### Step 3: Compile the Project + +Build the configured project: +```bash +cmake --build build +``` + +For multi-configuration generators (like Visual Studio), specify the build type: +```bash +# Release build (optimized) +cmake --build build --config Release + +# Debug build (with debug symbols) +cmake --build build --config Debug +``` + +--- + +## Running the Simulator + +The executable location depends on your generator and configuration: + +| Generator | Executable Location | +|-----------|---------------------| +| MinGW Makefiles / Unix Makefiles | `build/mms` or `build/mms.exe` | +| Visual Studio (Debug) | `build/Debug/mms.exe` | +| Visual Studio (Release) | `build/Release/mms.exe` | +| Ninja | `build/mms` or `build/mms.exe` | + +Run the simulator: +```bash +# For Unix-like systems +./build/mms + +# For Windows (MinGW) +./build/mms.exe + +# For Visual Studio builds +./build/Debug/mms.exe +``` + +--- + +## Testing + +If you configured the project with `-DBUILD_TESTING=ON`, run the test suite using CTest: +```bash +ctest --test-dir build --output-on-failure +``` + +**Options:** +- `--output-on-failure`: Displays test output only when tests fail +- `-V` or `--verbose`: Shows detailed output for all tests +- `-R `: Run only tests matching the regular expression + +### Running Specific Tests +```bash +# Run tests matching a pattern +ctest --test-dir build -R TrivialEquality --output-on-failure + +# Run tests verbosely +ctest --test-dir build -V +``` + +--- + +## Troubleshooting + +### CMake Configuration Fails + +- Verify CMake is installed: `cmake --version` +- Ensure a C++ compiler is in your PATH +- Try specifying a generator explicitly with `-G` + +### Build Errors + +- Check that all prerequisites are installed +- Ensure your compiler supports C++11 or higher +- Try cleaning and reconfiguring: +```bash + rm -rf build/ + cmake -B build + cmake --build build +``` + +### Cannot Find Executable + +- Check the executable location table above +- Verify the build completed without errors +- Look in `build/Debug/` or `build/Release/` for Visual Studio builds + +### Test Failures + +- Ensure you configured with `-DBUILD_TESTING=ON` +- Check that GoogleTest was successfully downloaded and built +- Run tests with `-V` flag for detailed output + +--- + +## Additional Resources + +- [CMake Documentation](https://cmake.org/documentation/) +- [GoogleTest GitHub](https://github.com/google/googletest) From 60a8c9ee34ad9d87abcee75d0f3564ca76bef774 Mon Sep 17 00:00:00 2001 From: Mutahir <123005041+kazurem@users.noreply.github.com> Date: Thu, 11 Dec 2025 00:15:58 +0500 Subject: [PATCH 06/23] Add contributions guide for MicroMouse Simulator Added a comprehensive contributions guide for the MicroMouse Simulator project, covering prerequisites, development workflow, coding standards, and submission guidelines. --- CONTRIBUTIONS.md | 454 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 454 insertions(+) create mode 100644 CONTRIBUTIONS.md diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md new file mode 100644 index 0000000..c42187e --- /dev/null +++ b/CONTRIBUTIONS.md @@ -0,0 +1,454 @@ +# ๐Ÿค Contributing to MicroMouse Simulator + +Thank you for your interest in contributing to the MicroMouse Simulator project! This guide will help you get started with contributing code, reporting issues, and following our development practices. + +--- + +## ๐Ÿ“‹ Table of Contents + +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Development Tools Setup](#development-tools-setup) +- [Testing Guidelines](#testing-guidelines) +- [Submitting Changes](#submitting-changes) +- [Reporting Issues](#reporting-issues) +- [Review Process](#review-process) + +--- + +## ๐Ÿš€ Getting Started + +### Prerequisites + +Before contributing, ensure you have: + +- **Git** installed and configured +- **CMake** (version 3.16+) +- **C++ Compiler** (GCC, Clang, MSVC, or MinGW) which supports C++17 and above +- **Clang-Format** (prefarably from the LLVM toolchain) +- **Clang-Tidy** (optional but recommended) +- **VSCode** (recommended IDE) + +### Setting Up Your Development Environment + +1. **Fork the Repository** + + Click the "Fork" button on GitHub and **disable** the "Copy the main branch only" option to ensure you get the `dev` branch. + +2. **Clone Your Fork** +```bash + git clone https://github.com/YOUR_USERNAME/MicroMouse-Simulator + cd MicroMouse-Simulator +``` + +3. **Add Upstream Remote** +```bash + git remote add upstream https://github.com/kr8457/MicroMouse-Simulator +``` + +4. **Switch to Development Branch** +```bash + git checkout dev +``` + +5. **Keep Your Fork Synchronized** +```bash + git pull upstream dev +``` + +--- + +## ๐Ÿ”„ Development Workflow + +### Branching Model + +We follow a **feature branch workflow** with two main branches: + +- **`main`**: Production-ready code (protected, no direct pushes) +- **`dev`**: Active development branch (all features merge here first) + +### Creating a Feature Branch + +1. **Ensure you're on the latest `dev` branch:** +```bash + git checkout dev + git pull upstream dev +``` + +2. **Create a descriptive feature branch:** +```bash + # Use descriptive names that explain what you're working on + git checkout -b feature/add-dijkstra-algorithm + git checkout -b fix/maze-generation-bug + git checkout -b docs/update-readme +``` + + **Branch naming conventions:** + - `feature/` - New features or enhancements + - `fix/` - Bug fixes + - `docs/` - Documentation updates + - `refactor/` - Code refactoring + - `test/` - Test additions or modifications + +3. **Make your changes and commit regularly:** +```bash + git add . + git commit -m "Add Dijkstra pathfinding algorithm" +``` + +4. **Push your branch to your fork:** +```bash + git push -u origin feature/add-dijkstra-algorithm +``` + +5. **Create a Pull Request:** + - Go to GitHub and open a PR from your branch to the `dev` branch + - Fill out the PR with details about your changes + - [Link](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) any relevant issues. + +### Syncing Your Fork + +Always keep your fork up to date: +```bash +# Fetch upstream changes +git fetch upstream + +# Update your dev branch +git checkout dev +git merge upstream/dev + +# Update your feature branch with latest dev changes +git checkout your-feature-branch +git rebase dev +``` + +> [!IMPORTANT] +> Always run `git pull` regularly to keep your local repository synchronized with the remote. + +--- + +## ๐Ÿ’ป Coding Standards + +### Naming Conventions + +#### 1. File Names +Use **PascalCase** for all source files: +``` +โœ… Good: +- MazeGen.cpp / MazeGen.hpp +- PathFinder.cpp / PathFinder.hpp +- RobotController.cpp / RobotController.hpp + +โŒ Bad: +- maze_gen.cpp +- pathfinder.cpp +- robot-controller.cpp +``` + +**File Extensions:** +- `.cpp` - C++ source files +- `.hpp` - C++ header files + +#### 2. Variable Names +Use **snake_case** for variables. Names should be descriptive and self-explanatory: +```cpp +โœ… Good: +int cell_count; +double path_length; +bool is_visited; +std::vector current_path; + +โŒ Bad: +int cc; +double pl; +bool v; +std::vector cp; +``` + +#### 3. Class Names +Use **PascalCase** for class names: +```cpp +โœ… Good: +class MazeGenerator; +class PathFinder; +class RobotController; + +โŒ Bad: +class maze_generator; +class pathfinder; +class robot_controller; +``` + +#### 4. Function Names +Use **snake_case** for function names: +```cpp +โœ… Good: +void generate_maze(); +int calculate_distance(); +bool is_wall_present(); + +โŒ Bad: +void generateMaze(); +int calculateDistance(); +bool isWallPresent(); +``` + +#### 5. Constants and Macros +Use **UPPER_SNAKE_CASE** for constants: +```cpp +โœ… Good: +const int MAX_MAZE_SIZE = 16; + +โŒ Bad: +const int maxMazeSize = 16; +``` +--- + +## ๐Ÿ› ๏ธ Development Tools Setup + +### Clang-Format Configuration + +Clang-Format ensures consistent code formatting across the project. + +#### Installation + +Install the LLVM toolchain to get Clang-Format: + +**Windows:** +```bash +# Download from https://releases.llvm.org/ +# Or use Chocolatey +choco install llvm +``` + +**Linux (Ubuntu/Debian):** +```bash +sudo apt-get install clang-format +``` + +**macOS:** +```bash +brew install clang-format +``` + +#### VSCode Integration + +1. Install the **C/C++** extension by Microsoft +2. Open VSCode Settings (`Ctrl+,` or `Cmd+,`) +3. Search for "cpp format" +4. Set the following options: + - **C_Cpp: Clang_format_path**: Path to your clang-format executable + - **C_Cpp: Clang_format_style**: `file` (uses `.clang-format` in project root) + - **Editor: Format On Save**: Enable this for automatic formatting + +#### Manual Formatting + +Format a single file: +```bash +clang-format -i src/MazeGen.cpp +``` + +Format all files: +```bash +#works on git bash if you are in windows +find src include -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i +``` + +### Clang-Tidy Configuration + +Clang-Tidy provides static analysis and linting for C++ code. + +#### VSCode Integration + +1. Install the **clangd** extension (disable C/C++ IntelliSense if using clangd) +2. Add to your VSCode `settings.json`: +```json +{ + "clangd.arguments": [ + "--compile-commands-dir=${workspaceFolder}/build", + "--clang-tidy" + ] +} +``` + +3. Generate compilation database: +```bash +cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +``` + +#### Running Clang-Tidy Manually +```bash +clang-tidy src/MazeGen.cpp -p build/ +``` +--- + +## ๐Ÿ“ค Submitting Changes + +### Commit Guidelines + +Write clear, concise commit messages following the **Conventional Commits** format: +``` +(): + + + +