README update

README.md

@@ -1,117 +1,172 @@
-# About
+# Crafter.Build
 
-This is a simple and easy to use C++ build system for Linux designed for use with C++20 modules in mind, it uses JSON based project files.
+A modern, cross-platform C++ build system designed specifically for C++20 modules. Built with simplicity and flexibility in mind.
 
-# Install
+## Features
 
-## Prerequisites:
-```
+- **C++20 Modules Support**: Native support for modern C++ module systems
+- **JSON-based Configuration**: Easy-to-read project configuration files
+- **Multi-Configuration Builds**: Debug and Release builds with customizable settings
+- **Dependency Management**: Easy integration with external projects
+- **Testing Framework**: Built-in test execution capabilities
+
+## Installation
+
+### Prerequisites
+```bash
 lld
 clang
 git
 lldb
 onetbb
 glslang
+vulkan-devel
 ```
 
-## Build from source
+### Build from Source
 ```bash
-git clone https://github.com/Catcrafts/Crafter.Build.git
+git clone https://forgejo.catcrafts.net/Catcrafts/Crafter.Build.git
 cd Crafter.Build
 ./build.sh
 ```
-(optionally add to path)
+(Optionally add to your PATH for global access)
 
-# How to use
+## Getting Started
 
-## Quickstart
+### Quickstart Guide
 
-create a ``project.json`` in an empty folder, open it in your preferred text editor.
-Create a basic project file, with a base configuration and debug and release configuration
-```JSON
+1. Create a `project.json` file in your project directory:
+```json
 {
     "name": "hello-world",
     "configurations": [
         {
-            "name": "base",
-            "standard": "c++26",
-            "source_files": ["main"],
-            "module_files": [],
-            "build_dir": "./build",
-            "output_dir": "./bin"
+            "name": "executable",
+            "implementations": ["main"],
         },
         {
-            "name": "debug",
-            "extends": ["base"],
-            "optimization_level": "0"
-        }
-        {
-            "name": "release",
-            "extends": ["base"],
-            "optimization_level": "3"
-        }
+            "name": "executable-debug",
+            "extends": ["executable"],
+            "debug": true
+        },
     ]
 }
 ```
-Save and close the file, create a ``main.cpp``
+
+2. Create `main.cpp`:
 ```cpp
 #include <print>
 int main() {
     std::println("Hello World!");
 }
 ```
-Save and close, then run ``crafter-build -c debug``. Now you can run the ``hello-world`` executable that has appeared in the ``bin`` folder
 
-## CLI arguments
+3. Build and run:
+```bash
+crafter-build build debug -r
+```
 
-``--help`` Displays a help message.
+## Command Line Interface
 
-``-c`` The name of the configuration to build.
+```bash
+# Build a specific configuration
+crafter-build build [configuration]
 
-``-p`` The path to the project file, defaults to ``project.json``.
+# Run a specific test
+crafter-build test [test]
 
-``-o`` Overrides the output folder.
+# Run all tests
+crafter-build test
 
-``-r`` Runs the executable after building.
+# Display help information
+crafter-build --help
 
-## configuration properties
-``name`` Name of the configuration.
+# Specify project file path (defaults to project.json)
+-p /path/to/project.json
 
-``standard`` C++ standard that this configuration uses, please refer to the [relevant clang documentation](https://clang.llvm.org/cxx_status.html), defaults to ``c++26``.
+# Run executable after building
+-r
+```
 
-``source_files`` All source files of the project ``.cpp`` extension is assumed.
+## Test Configuration
 
-``module_files`` All C++ 20 module files of the project ``.cppm`` extension is assumed.
+Tests are defined in the `tests` array of your project file. A typical test configuration depends on your main project:
 
-``additional_files`` Files that will be copied to the output_dir.
+```json
+"tests": [
+    {
+        "name": "should-compile",
+        "implementations": ["tests/ShouldCompile"],
+        "dependencies": [
+            {
+                "path": "./project.json",
+                "configuration": "lib-shared"
+            }
+        ]
+    }
+]
+```
 
-``build_dir`` The directory where intermediate files are stored.
+### Writing Test Files
 
-``output_dir`` The directory where the output files will be placed.
+Test files must follow a specific format:
+- Export a C-compatible function named `RunTest()`
+- The `RunTest()` function must return `nullptr` if the test passes, or a pointer to an error message string if it fails
 
-``type`` The type of the project: ``executable``, ``library``, ``shared-library``, defaults to ``executable``.
+Example test implementation:
+```cpp
+import std;
+using namespace std;
 
-``extends`` An array of configuration names that this configuration extends, later elements in the array take priority over previous ones.
+extern "C" {
+    string* RunTest() {
+        // Perform your test logic here
+        int expected = 42;
+        int actual = 5 * 8 + 2; // Should equal 42
         
-``optimization_level`` Please refer to the [relevant clang documentation](https://clang.llvm.org/docs/CommandGuide/clang.html#code-generation-options), defaults to ``0``.
+        if (actual != expected) {
+            return new string("Test failed: expected " + to_string(expected) + ", but got " + to_string(actual));
+        }
         
-``dependencies`` An object array of the dependencies of this project, example:
+        // Return nullptr to indicate success
+        return nullptr;
+    }
+}
+```
+
+## Configuration Properties
+
+### Basic Properties
+- **name**: Name of the configuration
+- **standard**: C++ standard (default: `c++26`)
+- **interfaces**: C++20 module files (`.cppm` extension)
+- **implementations**: Source files (`.cpp` extension)
+- **additional_files**: Files copied to output directory
+- **build_dir**: Directory for intermediate build files  (default: `build`)
+- **output_dir**: Directory for final output files (default: `bin`)
+- **type**: Project type (`executable`, `library`, `shared-library`, default: `executable`)
+- **extends**: Array of configuration names to extend, later entries overwrite previous ones
+- **debug**: Boolean enabling debug mode (default: `false`)
+
+### Dependencies
+Both local and git dependencies are supported:
+
+For git dependencies branch and commit are mutually exclusive, if neither is supplied the latest commit on the default branch is chosen
 ```json
 "dependencies": [
     {
         "path": "/home/Crafter.Build/project.json",
         "configuration": "debug-lib",
-        "commit":"af7eb61c3d92ab18f6aa6c139ac7211a908a24ee"
-    }
+    },
     {
         "path": "https://github.com/Catcrafts/Crafter.Build.git",
         "configuration": "debug-lib",
-        "branch":"master"
+        "branch": "master",
+        "commit": "af7eb61c3d92ab18f6aa6c139ac7211a908a24ee"
     }
 ]
 ```
-This will now link the library of Crafter.Build in the configuration you use this in. ``commit`` and ``branch`` are optional parameters, if omitted the latest commit on the default branch is used.
 
-``target`` Clang triplet this configuration uses, please refer to the [relevant clang documentation](https://clang.llvm.org/docs/CrossCompilation.html#target-triple).
+## License
 
-Note: the WASI SDK needs to be installed to compile to webassmbly, and ``$WASI_SDK_PATH`` needs to be set, please refer to the [wasi-sdk installation guide](https://github.com/WebAssembly/wasi-sdk?tab=readme-ov-file#install).
+This project is licensed under the LGPL v3 License - see the LICENSE file for details.

implementations/main.cpp

@@ -22,8 +22,16 @@ import std;
 using namespace Crafter;
 namespace fs = std::filesystem;
 int main(int argc, char* argv[]) {
-    if(std::string(argv[1]) == "--help") {
-        std::println("--help\tDisplays this help message.\n-c The name of the configuration to build.\n-p The path to the project file. defualts to project.json\n-o Overrides the output folder.\n-r Runs the executable after building.");
+    if(std::string(argv[1]) == "--help" || std::string(argv[1]) == "help" ) {
+        std::println("Crafter.Build - A modern build system for C++ projects\n");
+        std::println("Usage: crafter-build [command] [options]");
+        std::println("\nCommands:");
+        std::println("  build\t\tBuild the project");
+        std::println("  test\t\tRun project tests");
+        std::println("\nOptions:");
+        std::println("  --help\tDisplay this help message");
+        std::println("  -p PATH\tSpecify the project file path (default: project.json)");
+        std::println("  -r\t\tRun the built executable after building");
         return 0;
     }
     if(argc < 2 && std::string(argv[1]) == "build") {

project.json

@@ -44,6 +44,26 @@
                     "configuration":"lib-shared"
                 }
             ]
+        },
+        {
+            "name": "example-test",
+            "implementations": ["tests/ExampleTest"],
+            "dependencies": [
+                {
+                    "path":"./project.json",
+                    "configuration":"lib-shared"
+                }
+            ]
+        },
+        {
+            "name": "test-structure",
+            "implementations": ["tests/TestStructure"],
+            "dependencies": [
+                {
+                    "path":"./project.json",
+                    "configuration":"lib-shared"
+                }
+            ]
         }
     ]
 }