Add more documentation to README.md

README.md

@@ -30,3 +30,156 @@ Projects need to follow some rules to allow building them with shuriken.
 - Modules must be defined in source files using the same path and name as the module, replacing `.` with `/`. (For example, the module `foo.bar.baz` must be defined in `src/foo/bar/baz.cppm`.)
 - Modules can only be defined in one file. Splitting module interface and implementation is not supported.
 - Clang should be used as the compiler for the default target. While the compiler itself is configurable, the build dependency detection for modules uses `clang-scan-deps`. Other targets can use other compilers, since dependency detection is always done using the default target.
+
+
+## Installation
+
+While you could theoretically install the shuriken script in your system, it is recommended to instead add it to your project.
+
+It's just a single Python file, and adding it to your project has several advantages. For example, if someone wants to build your project, they don't need to install yet another obscure build tool on their system. You also avoid issues because of different shuriken versions and you can modify the build script if needed.
+
+However, you do need to install the dependencies used by shuriken on your system if you don't have them installed already. These are the Python library [PyYAML](https://pyyaml.org/), the [Ninja](https://ninja-build.org/) build system (minimum version 1.10) and of course the [Clang](https://clang.llvm.org/) compiler.
+
+On Debian: `apt install pyyaml ninja-build clang`
+
+On Arch Linux: `pacman -S python-yaml ninja clang`
+
+Finally, copy the file `src/shuriken.py` from this repository to your project and make sure it's executable (`chmod 755`).
+
+You can put the file anywhere you want, one example would be to use `tools/shuriken.py`. You can then define a shell alias like `alias shuriken=tools/shuriken.py` so that you can easily run commands like `shuriken build`. Alternatively, copy the file to `shuriken` in the root directory of your project and run it like `./shuriken build`.
+
+
+## Configuration
+
+To run shuriken, a build configuration is required. A shuriken config is a YAML file that defines the build targets as well as build parameters like which compiler and linker flags to use.
+
+By default, shuriken looks for a file `shuriken.yaml` in the project root directory, although you can specify a different config using the `-c` parameter.
+
+A minimal shuriken config looks like this:
+
+```yaml
+default_target: linux
+
+targets:
+  linux:
+    output_file: exampleapp
+```
+
+This will build all C++ source files from `src` using `clang++` and output an executable file in `build/linux/exampleapp`.
+
+A complete example using all available config settings looks as follows. Unless specified otherwise, the shown values are the defaults.
+
+```yaml
+# Directory containing the source files
+source_dir: src
+
+# Directory where build artifacts and the output files are stored
+build_dir: build
+
+# Default values that are used for every target unless overridden in "targets".
+# The specification is the same as for the targets below. The "_extra" keys
+# not intended to be set here, but can be used in "targets" to extend rather
+# than override settings. For example, you can define compile flags using
+# "cpp_flags" here and add target-specific flags in "cpp_flags_extra" without
+# overriding the defaults.
+defaults:
+  # Which compiler to use for C++ files
+  cpp_compiler: clang++
+
+  # Which C++ standard to use (value for "-std=" compile flag)
+  cpp_standard: c++20
+
+  # Compiler flags for compiling C++ files (default: empty)
+  # (Note that "-std=..." will be set automatically based on "cpp_standard"
+  # and should not be set here!)
+  cpp_flags: -Wall -Wextra -Werror -pedantic
+  #cpp_flags_extra:
+  
+  # Linker flags for linking the output file (default: empty)
+  # (These flags are used at the start of the linker command, see also
+  # "linker_args" below.)
+  linker_flags:
+  #linker_flags_extra:
+  
+  # Additional linker arguments that are *appended* to the linker command,
+  # i.e. following the list of object files built by the compiler.
+  # This should be used to specify libraries to link against, since the order
+  # of arguments in linker commands is relevant. (default: empty)
+  linker_args: -lSDL3 -lSDL3_image
+  #linker_args_extra:
+  
+  # File name of the output file, i.e. the executable generated by the linker.
+  # This is relative to "{build_dir}/{target}/" and can contain subdirectories.
+  # Usually this is target-specific and should therefore be set in "targets".
+  # (default: empty)
+  output_file:
+  
+  # The command for running the built project when using "shuriken run".
+  # This command will be run in a shell and can therefore contain shell syntax.
+  # It supports two parameters: "{out}" will be replaced with the (relative)
+  # path of the output file, i.e. "{build_dir}/{target}/{output_file}".
+  # "{args}" will be replaced by any arguments given to "shuriken run".
+  # Defaults to running the output file.
+  run_command: ./{out} {args}
+
+# Which target (defined below in "targets") to build when calling shuriken
+# without specifying a target. This must be defined.
+# The default target is also used for scanning the project for build
+# dependencies (since "clang-scan-deps" might not work with other compilers,
+# e.g. when building for WebAssembly).
+default_target: linux
+
+# Definitions for build targets. The keys are the names of the target, the
+# values are mappings following the same specification as "defaults" above).
+# (Note that the target names don't have any special meaning, e.g. "linux"
+# and "web" are just arbitrary strings. They are used in file paths however,
+# so you should stick to alphanumeric characters, "-" and "_" to avoid issues).
+targets:
+  # Example for a target that uses the values from "defaults" as defined above
+  # and only sets the output filename (required unless defined in "defaults").
+  linux:
+    output_file: exampleapp
+
+  # Example for a target using emscripten to compile the app to WebAssembly.
+  # Every setting not specified here will be taken from "defaults" above.
+  web:
+    # Override which compiler to use.
+    cpp_compiler: em++
+    
+    # Use the default flags from "defaults.cpp_flags", but add an additional
+    # flag for setting a custom include path.
+    cpp_flags_extra: -Ivendor
+    
+    # Override linker arguments. Instead of using "-lSDL", we need to link
+    # against static libraries for a web build. Also specifies other arguments
+    # specific to emscripten.
+    # (We use a YAML multiline string here for better readability. It has the
+    # same meaning as a regular string. See https://yaml-multiline.info/).
+    linker_args: >-
+      lib/web/libSDL3.a
+      lib/web/libSDL3_image.a 
+      --use-preload-plugins
+      --preload-file assets/
+    
+    # Set a different output filename. Emscripten will generate an HTML file
+    # with this name, as well as some additional files in the same directory.
+    # We use a subdirectory here to separate the files from other build files.
+    output_file: output/index.html
+    
+    # Override the command that runs when using "shuriken run". We cannot
+    # execute an HTML file, so we start an ad-hoc web server using Python
+    # instead which will serve the generated files.
+    run_command: python -m http.server -d build/web/output
+```
+
+
+## Command usage
+
+To get an overview of all commands and options, use `shuriken --help` or `shuriken COMMAND --help`.
+
+The most common commands are as follows. If no target is specified, shuriken will use the default target as defined in the config.
+
+- `shuriken [-t TARGET] build`: Builds the application for the given target. This is the default command, so just `shuriken` works as well.
+- `shuriken [-t TARGET] run`: Builds the application and runs it (see `run_command` in the config).
+- `shuriken [-t TARGET] clean`: Removes all generated files for the given target from the build directory, including the output file.
+- `shuriken clean --all`: Removes all generated files of all targets from the build directory.