diff --git a/.gitignore b/.gitignore
index 79c01ce..7ae8fcd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,7 +50,7 @@ Resources/embed.exe
# Natural Docs cache data
DocsGeneration/ND_Config/Working\ Data
-docs/
+# docs/
# Language server files
.cache/
diff --git a/DefaultYAMLs/DefaultScriptInfo.yaml b/DefaultYAMLs/DefaultScriptInfo.yaml
index 9b61dd6..5b1f5f9 100644
--- a/DefaultYAMLs/DefaultScriptInfo.yaml
+++ b/DefaultYAMLs/DefaultScriptInfo.yaml
@@ -141,7 +141,7 @@ Dependencies:
# (Optional) Import dependency configuration from a YAML file if this field exists
# All other fields (Name, Platforms, etc...) are not needed if this field exists
# For Git source: Path is relative to the git repository root
- # For Local source: Path is relative to the script directory.
+ # For Local source: Path is relative to the path specified under `Local`
# If neither source exists, local source with root script directory is assumed.
ImportPath: "config/dependency.yaml"
diff --git a/README.md b/README.md
index ed8ae5e..a40a439 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,24 @@
# runcpp2
-
+
-A cross-platform declarative and scriptable (WIP) build system for c++ with the addition of letting you run any c++ files as a script, just like python!
+runcpp2 is a simple declarable, scriptable, flexible cross-platform build system build system for c or c++
-### 🛠️ Prerequisites
-- Any C++ compiler. The default user config only has g++ and msvc profiles. But feel free to
+- 🚀 **Simple**: `runcpp2 main.cpp`, this is all you need to get started
+- 📝 **Declarable**: *Quick, Concise, Minimal* YAML format
+- 🔧 **Scriptable**: *Customize, Run And Debug* your build pipeline with c++, or just use it as a script.
+ No longer need to juggle between CMake, Python, Bash, Batch, Lua, etc...
+- 🪜 **Flexible**: *YAML* for small project, *c++* for finer control
+
+For more information, see [Full Documentation](https://neko-box-coder.github.io/runcpp2/latest/)
+
+## 🛠️ Prerequisites
+- Any c or c++ compiler. The default user config only has g++ and msvc profiles. But feel free to
add other compilers.
-### 📥️ Installation
+## 📥️ Installation
You can either build from source or use the binary release
-To build from source:
-1. Clone the repository with `git clone --recursive https://github.com/Neko-Box-Coder/runcpp2.git`
-2. Run `Build.sh` or `Build.bat` to build
-
Binary Release (Only Linux and Windows for now):
[https://github.com/Neko-Box-Coder/runcpp2/releases](https://github.com/Neko-Box-Coder/runcpp2/releases)
@@ -22,78 +26,50 @@ Binary Release (Only Linux and Windows for now):
Finally, you just need to add runcpp2 binary location to the `PATH` environment variable and
you can run c++ files anywhere you want.
-### ⚡️ Getting Started
+## ⚡️ Getting Started
-#### 1. Running directly
+### 1. Running source file directly
Suppose you have a c++ file called `script.cpp`, you can run it immediately by doing
+> *shell*
```shell
runcpp2 ./script.cpp
```
> [!NOTE]
-> On Unix, if you have added runcpp2 to your PATH and add this line `//bin/true;runcpp2 "$0" "$@"; exit;` to the top of your script, you can run the script directly by `./script.cpp `
+> On Unix, if you have added runcpp2 to your PATH and add this line `//bin/true;runcpp2 "$0" "$@"; exit $?;`
+> to the top of your script, you can run the script directly by `./script.cpp `
-#### 2. Watch and give compile errors
+---
+
+### 2. Watch and give compile errors
If you want to edit the script but want to have feedback for any error, you can use "watch" mode.
+> *shell*
```shell
runcpp2 --watch ./script.cpp
```
-#### 3. Adding script build settings
-If you want to add custom build settings such as compile/link flags, specify profile, etc.
-You will need to provide such settings to runcpp2 in the format of YAML.
-
-This build settings can either be embedded as comment in the script itself, or provided as
-a YAML file.
+---
-To generate a script build settings template, do
+### 3. Sepcifying Build Settings
+Build settings such as compile/link flags, external dependencies, command hooks, etc.
+can be spcified inlined inside a source file or as a separate yaml file in the format of YAML
-```shell
-# Embeds the build settings template as comment
-runcpp2 --create-script-template ./script.cpp
-
-# Creates the build settings template as dedicated yaml file
-runcpp2 --create-script-template ./script.yaml
-
-# Short form
-runcpp2 -t ./script.cpp
-```
+- To specify build settings in a dedicated yaml file:
+ - The yaml file in the same directory and share the same as the source file being run will be used
+- To specify inline build settings inside a source file:
+ - Put them inside a comment with `runcpp2` at the beginning of the build settings
+ - The inline build settings can exist in anywhere of the source file
+ - Both inline (but continuous) comments (`//`) and block comments are supported (`/* */`)
-This will generate the script build settings template for you.
-Everything is documented as comment in the template but here's a quick summary.
-
-- `RequiredProfiles`: To specify a specific profile for building for different platforms
-- `OverrideCompileFlags`: Compile flags to be added or removed from the current profile
-- `OverrideLinkFlags`: Same as `OverrideCompileFlags` but for linking
-- `OtherFilesToBeCompiled`: Other source files you wish to be compiled.
-- `Dependencies`: Any external libraries you wish to use. See next section.
-
-> [!NOTE]
-> Settings in the script info are passed directly to the shell. Be cautious when using user-provided input in your build commands.
-
-#### 4. Using External Libraries
-
-To use any external libraries, you need to specify them in the Dependencies section.
-Here's a quick run down on the important fields
-
-- `Source`: This specifies the source of the external dependency.
-It can either be type `Git` or `Local` where it will clone the repository if it is `Git` or
-copy the library folder in the filesystem if it is `Local`
-- `LibraryType`: This specifies the dependency type to be either `Static`, `Object`, `Shared`
-or `Header`
-- `IncludePaths`: The include paths relative to the root of the dependency folder
-- `LinkProperties`: Settings for linking
-- `Setup`, `Build` and `Cleanup`: List of shell commands for one time setup, building and
-cleaning up
-
-To access the source files of the dependencies, you can specify runcpp2 to build locally in
-the current working directory by passing the `--local` flag. This is useful when you want to
-look at the headers of the dependencies.
+For a complete list of build settings, see [Build Settings](https://neko-box-coder.github.io/runcpp2/latest/build_settings/) or generate the template with
+> *shell*
```shell
-runcpp2 --local ./script.cpp
+runcpp2 --create-script-template ./script.cpp # Embeds the build settings template as comment
+runcpp2 --create-script-template ./script.yaml # Creates the build settings template as dedicated yaml file
+runcpp2 -t ./script.cpp # Short form
```
-This will create a `.runcpp2` folder in the current working directory, and all the builds and dependencies will be inside it.
+
diff --git a/TODO.md b/TODO.md
index 8569cec..97d2922 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,6 +1,9 @@
TODO:
- Allow runcpp2 to be library
-- Add the ability to specify different profiles for different source files
+- Add the ability to specify different profiles(?)/defines for different source files
+- Add the ability to use symlinks for local dependency
+- Add the ability to append defines coming from the dependencies
+- Add the ability for user to specify custom substitution options which applies to all fields
- Ability to compile runcpp2 as single cpp
- Ability to skip DefaultPlatform and DefaultProfile
- Async compile
@@ -26,3 +29,6 @@ TODO:
- Add version for user config and prompt for update
- Output compile_command.json
- Allow Languages to override FileExtensions in compiler profile (?)
+
+
+
diff --git a/mkdocs/docs/Runcpp2Logo.png b/mkdocs/docs/Runcpp2Logo.png
new file mode 100644
index 0000000..81a7cdd
Binary files /dev/null and b/mkdocs/docs/Runcpp2Logo.png differ
diff --git a/mkdocs/docs/build_settings.md b/mkdocs/docs/build_settings.md
new file mode 100644
index 0000000..dd7e534
--- /dev/null
+++ b/mkdocs/docs/build_settings.md
@@ -0,0 +1,488 @@
+# Build Settings
+
+## Special Types
+
+### `platform profile map`
+- Type: `Platforms Map With Profiles Map`
+- Description: A map of platforms with a map of profiles.
+
+??? TODO
+ If platform and profile are not specified, the default platform and profile are used.
+
+???+ Example
+ ```yaml
+ Windows:
+ "g++":
+ ExampleSetting: "ExampleValue"
+ Linux:
+ "g++":
+ ExampleSetting: "ExampleValue"
+ MacOS:
+ "g++":
+ ExampleSetting: "ExampleValue"
+ ```
+
+### `platform profile list`
+- Type: `Platforms Map With Profiles List`
+- Description: A map of platforms with a list of profiles.
+
+???+ Example
+ ```yaml
+ Windows: ["g++", "msvc"]
+ Linux: ["g++"]
+ MacOS: ["g++"]
+ ```
+
+## Special Keywords
+
+### `DefaultPlatform`
+- Type: `string key`
+- Description: Evaluates to the host platform.
+
+### `DefaultProfile`
+- Type: `string key`
+- Description: Evaluates to the preferred profile the user has set in the config file.
+
+---
+
+## Settings
+
+- `PassScriptPath`
+ - Type: `bool`
+ - Optional: `true`
+ - Default: `false`
+ - Description: Whether to pass the script path as the second parameter when running in additional to the binary path.
+- `Language`
+ - Type: `string`
+ - Optional: `true`
+ - Default: Determined by file extension
+ - Description: The language of the script.
+- `BuildType`
+ - Type: `enum string`, can be one of the following:
+ - `Executable`
+ - `Static`
+ - `Shared`
+ - `Objects`
+ - Optional: `true`
+ - Default: `Executable`
+ - Description: The type of output to build.
+- `RequiredProfiles`
+ - Type: `platform profile list`
+ - Optional: `true`
+ - Default: None
+ - Description: The profiles that are required for the script to be built. No profiles are required if this field is empty.
+- `OverrideCompileFlags`
+ - Type: `platform profile map`
+ - Optional: `true`
+ - Default: None
+ - Description: The compile flags to override for each platform and profile.
+ - Child Fields:
+ - `Remove`
+ - Type: `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The compile flags to remove for each platform and profile.
+ - `Append`
+ - Type: `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The compile flags to append for each platform and profile.
+- `OverrideLinkFlags`
+ - Type: `platform profile map` with child fields
+ - Optional: `true`
+ - Default: None
+ - Description: The link flags to override for each platform and profile.
+ - Child Fields:
+ - `Remove`
+ - Type: `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The link flags to remove for each platform and profile.
+ - `Append`
+ - Type: `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The link flags to append for each platform and profile.
+- `OtherFilesToBeCompiled`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The source files to be compiled for each platform and profile.
+- `IncludePaths`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The include paths to be used for each platform and profile.
+- `Defines`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The defines to be used for each platform and profile.
+- `Setup`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The setup commands to be used for each platform and profile.
+- `PreBuild`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The pre-build commands to be used for each platform and profile.
+- `PostBuild`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The post-build commands to be used for each platform and profile.
+- `Cleanup`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The cleanup commands to be used for each platform and profile.
+- `Dependencies`
+ - Type: `list` of `dependency entry`
+ - Optional: `true`
+ - Default: None
+ - Description: The dependencies to be used for each platform and profile.
+
+### `dependency entry`
+- Type: `map`
+- Child Fields:
+ - `Name`
+ - Type: `string`
+ - Optional: `false`, `true` only if `Source.ImportPath` is specified
+ - Default: None
+ - Description: The name of the dependency.
+ - `Platforms`
+ - Type: `list` of `string`
+ - Optional: `false`
+ - Default: None
+ - Description: The platforms to be used for the dependency.
+ - `Source`
+ - Type: `map` with child fields
+ - Optional: `false`
+ - Default: None
+ - Description: The source of the dependency.
+ - Child Fields:
+ - `ImportPath`
+ - Type: `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The path to the dependency configuration file from the root repository of `Git.URL` or `Local.Path`
+ - `Git`
+ - Type: `map` with child fields
+ - Optional: `true` if `ImportPath` is specified or `Local` is specified
+ - Default: None
+ - Description: The git source of the dependency.
+ - Child Fields:
+ - `URL`
+ - Type: `string`
+ - Optional: `false`
+ - Default: None
+ - Description: The url of the git repository.
+ - `Local`
+ - Type: `map` with child fields
+ - Optional: `true` if `ImportPath` is specified or `Git` is specified
+ - Default: None
+ - Description: The local source of the dependency.
+ - Child Fields:
+ - `Path`
+ - Type: `string`
+ - Optional: `false`
+ - Default: None
+ - Description: The path to the local dependency.
+ - `LibraryType`
+ - Type: `enum string`, can be one of the following:
+ - `Static`
+ - `Object`
+ - `Shared`
+ - `Header`
+ - `IncludePaths`
+ - Type: `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The include paths to be used for the dependency.
+ - `LinkProperties`
+ - Type: `map` with child fields
+ - Optional: `true` if `LibraryType` is `Header`
+ - Default: None
+ - Description: The link properties to be used for the dependency.
+ - Child Fields:
+ - `SearchLibraryNames`
+ - Type: `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The library names to be searched for when linking against the script.
+ - `ExcludeLibraryNames`
+ - Type: `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The library names to be excluded from being linked against the script.
+ - `SearchDirectories`
+ - Type: `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The directories to be searched for the dependency binaries.
+ - `AdditionalLinkOptions`
+ - Type: `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The additional link options to be used for the dependency.
+ - `Setup`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The setup commands to be used for the dependency.
+ - `Build`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The build commands to be used for the dependency.
+ - `Cleanup`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The cleanup commands to be used for the dependency.
+ - `FilesToCopy`
+ - Type: `platform profile map` with `list` of `string`
+ - Optional: `true`
+ - Default: None
+ - Description: The files to be copied to the output directory for each platform and profile.
+
+
+
+## Template
+
+```yaml
+# This is the template for specifying build settings.
+# Many of the settings are passed directly to the shell.
+# Be cautious when using user-provided input in your build commands to avoid potential security risks.
+# Output from commands such as Setup or Cleanup won't be shown unless log level is set to info.
+# If the default is not mentioned for a setting, it will be empty.
+
+# Each of the platform dependent settings can be listed under
+# - DefaultPlatform
+# - Windows
+# - Linux
+# - MacOS
+# - Unix
+
+# You can find all the profiles in your config folder.
+# This can be found by running `runcpp2 --show-config-path`.
+# Specifying "DefaultProfile" in the profile name will allow any profiles
+# and use the user's preferred one.
+
+# (Optional) Whether to pass the script path as the second parameter when running. Default is false
+PassScriptPath: false
+
+# (Optional) Language of the script. Default is determined by file extension
+Language: "c++"
+
+# (Optional) The type of output to build. Default is Executable
+# Supported types:
+# - Executable: Build as executable that can be run
+# - Static: Build as static library (.lib/.a)
+# - Shared: Build as shared library (.dll/.so)
+# - Objects: Only compile to object files without linking
+BuildType: Executable
+
+# TODO: Rename this
+# (Optional) Allowed profiles for the script for each platform.
+# Any profiles will be used if none is specified for the platform.
+RequiredProfiles:
+ Windows: ["g++"]
+ Linux: ["g++"]
+ MacOS: ["g++"]
+
+# (Optional) Override the default compile flags for each platform.
+OverrideCompileFlags:
+ # Target Platform
+ DefaultPlatform:
+ # Profile with the respective flags to override
+ "g++":
+ # (Optional) Flags to be removed from the default compile flags, separated by space
+ Remove: ""
+
+ # (Optional) Additional flags to be appended to the default compile flags, separated by space
+ Append: ""
+
+# (Optional) Override the default link flags for each platform.
+OverrideLinkFlags:
+ # Target Platform
+ DefaultPlatform:
+ # Profile with the respective flags to override
+ "g++":
+ # (Optional) Flags to be removed from the default link flags, separated by space
+ Remove: ""
+
+ # (Optional) Additional flags to be appended to the default link flags,
+ # separated by space
+ Append: ""
+
+# (Optional) Other source files (relative to script file path) to be compiled.
+OtherFilesToBeCompiled:
+ # Target Platform
+ DefaultPlatform:
+ # Target Profile
+ DefaultProfile:
+ - "./AnotherSourceFile.cpp"
+
+# (Optional) Include paths (relative to script file path) for each platform and profile
+IncludePaths:
+ # Target Platform
+ DefaultPlatform:
+ # Target Profile
+ DefaultProfile:
+ - "./include"
+ - "./src/include"
+
+# (Optional) Define cross-compiler defines for each platform and profile.
+# Defines can be specified as just a name or as a name-value pair.
+Defines:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ - "EXAMPLE_DEFINE" # Define without a value
+ - "VERSION_MAJOR=1" # Define with a value
+
+# (Optional) Setup commands are run once before the script is first built.
+# These commands are run at the script's location when no build directory exists.
+Setup:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ # List of setup commands
+ - "echo Setting up script..."
+
+# (Optional) PreBuild commands are run before each build.
+# These commands are run in the build directory before compilation starts.
+PreBuild:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ - "echo Starting build..."
+
+# (Optional) PostBuild commands are run after each successful build.
+# These commands are run in the output directory where binaries are located.
+PostBuild:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ - "echo Build completed..."
+
+# (Optional) Cleanup commands are run when using the --cleanup option.
+# These commands are run at the script's location before the build directory is removed.
+Cleanup:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ - "echo Cleaning up script..."
+
+# (Optional) The list of dependencies needed by the script
+Dependencies:
+ # Dependency name
+- Name: MyLibrary
+
+ # Supported platforms of the dependency
+ Platforms: [Windows, Linux, MacOS]
+
+ # Where to get and copy the dependency (Git, Local)
+ # Either Git or Local can exist, not both
+ Source:
+ # (Optional) Import dependency configuration from a YAML file if this field exists
+ # All other fields (Name, Platforms, etc...) are not needed if this field exists
+ # For Git source: Path is relative to the git repository root
+ # For Local source: Path is relative to the path specified under `Local`
+ # If neither source exists, local source with root script directory is assumed.
+ ImportPath: "config/dependency.yaml"
+
+ # Dependency or import YAML file exists in a git server, and needs to be cloned to build directory
+ Git:
+ # Git repository URL
+ URL: "https://github.com/MyUser/MyLibrary.git"
+
+ # Dependency or import YAML file exists in local filesystem directory,
+ # and needs to be copied to build directory
+ Local:
+ # Path to the library directory
+ Path: "./libs/LocalLibrary"
+
+
+ # Library Type (Static, Object, Shared, Header)
+ LibraryType: Static
+
+ # (Optional) Paths to be added to the include paths, relative to the dependency folder
+ IncludePaths:
+ - "src/include"
+
+ # (Optional if LibraryType is Header) Link properties of the dependency
+ LinkProperties:
+ # Properties for searching the library binary for each platform
+ DefaultPlatform:
+ # Profile-specific properties
+ "g++":
+ # The library names to be searched for when linking against the script.
+ # Binaries with linkable extension that contains one of the names will be linked
+ SearchLibraryNames: ["MyLibrary"]
+
+ # (Optional) The library names to be excluded from being searched.
+ # Works the same as SearchLibraryNames but will NOT be linked instead
+ ExcludeLibraryNames: []
+
+ # The path (relative to the dependency folder) to be searched for the dependency binaries
+ SearchDirectories: ["./build"]
+
+ # (Optional) Additional link flags for this dependency
+ AdditionalLinkOptions: []
+
+ # (Optional) Setup commands are run once when the dependency is populated
+ Setup:
+ # Target Platform
+ DefaultPlatform:
+ # Setup shell commands for the specified profile.
+ # Default commands are run in the dependency folder
+ # You can also use "DefaultProfile" if all the compilers run the same setup commands
+ "g++":
+ - "mkdir build"
+
+
+ # (Optional) Build commands are run every time before the script is being built
+ Build:
+ # Target Platform
+ DefaultPlatform:
+ # Target Profile
+ "g++":
+ - "cd build && cmake .."
+ - "cd build && cmake --build ."
+
+ # (Optional) Cleanup commands are run when the reset option is present. Normally nothing needs
+ # to be done since the dependency folder will be removed automatically.
+ Cleanup:
+ # Target Platform
+ Linux:
+ # Target Profile
+ "g++":
+ - "sudo apt purge MyLibrary"
+
+ # (Optional) Files to be copied to next to output binary for each platform and profile
+ FilesToCopy:
+ # Target Platform
+ DefaultPlatform:
+ # Profile name
+ DefaultProfile:
+ # List of files to copy (relative to the dependency folder)
+ - "assets/textures/sprite.png"
+ Windows:
+ "msvc":
+ - "assets/textures/sprite.png"
+ - "assets/fonts/windows_specific_font.ttf"
+ Linux:
+ "g++":
+ - "assets/textures/sprite.png"
+ - "assets/shaders/linux_optimized_shader.glsl"
+
+```
diff --git a/mkdocs/docs/extra.css b/mkdocs/docs/extra.css
new file mode 100644
index 0000000..7827209
--- /dev/null
+++ b/mkdocs/docs/extra.css
@@ -0,0 +1,24 @@
+
+
+.md-header__button.md-logo {
+ // margin-top: 0;
+ // margin-bottom: 0;
+ // margin-right: 0;
+ // padding-right: 0;
+ // padding-top: 0;
+ // padding-bottom: 0;
+ width: 5rem;
+}
+
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+ width: 100%;
+ height: auto;
+ overflow: hidden;
+ //height: 50%;
+ //width: 100%;
+ //min-width: 3rem;
+ //display: block;
+ //margin-left: auto;
+ //margin-right: auto;
+}
diff --git a/mkdocs/docs/favicon.png b/mkdocs/docs/favicon.png
new file mode 100644
index 0000000..cdf6820
Binary files /dev/null and b/mkdocs/docs/favicon.png differ
diff --git a/mkdocs/docs/guides/basic_concepts.md b/mkdocs/docs/guides/basic_concepts.md
new file mode 100644
index 0000000..0eed269
--- /dev/null
+++ b/mkdocs/docs/guides/basic_concepts.md
@@ -0,0 +1,117 @@
+# Basic Concepts
+
+## Script File
+
+A script file is your entry point source file (typically a .cpp file) that runcpp2 uses to build
+with the settings specified either:
+
+- As inline comments in the source file:
+ ```cpp
+ /*runcpp2
+ RequiredProfiles:
+ Windows: ["msvc"]
+ Unix: ["g++"]
+ */
+ int main() { return 0; }
+ ```
+
+- Or as a separate YAML file with the same name:
+ ```
+ script.cpp # Your source file
+ script.yaml # Your build settings
+ ```
+
+The name of the final output will be the name of the script file, therefore a script file will
+always have a 1 to 1 relationship with the linker output, even if multiple sources are specified in
+the script file build settings.
+
+You can use any of your source files as a script file, or a dedicated .cpp file for building.
+
+---
+
+## Platforms And Profiles
+
+runcpp2 uses platforms and profiles to organize build settings.
+
+Platforms represent different host operating systems (not the target platform), while profiles
+represent different compilers toolchains and their configurations.
+
+### List Of Platforms
+
+runcpp2 supports the following platforms:
+
+- Windows
+- Linux
+- MacOS
+- Unix (applies to Linux and MacOS)
+
+??? TODO
+ Custom platforms
+
+### Default Profiles
+
+The default user configuration includes two compiler profiles:
+
+- **g++**: GNU c++ compiler (with alias "mingw")
+- **vs2022_v17+**: Visual Studio 2022 compiler (with aliases "msvc1930+", "msvc")
+
+### Specifying Platform/Profile Dependent Settings
+
+Most build settings in runcpp2 follow this structure:
+```yaml
+:
+ :
+ :
+ ...
+ :
+ :
+ ...
+```
+
+???+ example
+ ```yaml
+ OverrideCompileFlags:
+ Windows:
+ "g++":
+ Flags: "-O2 -Wall"
+ "msvc":
+ Flags: "/O2"
+ Linux:
+ "g++":
+ Flags: "-O3"
+ ```
+
+There are two special keywords for more flexible configuration:
+
+- **DefaultPlatform**: Settings that apply to any platform that doesn't have explicit settings
+- **DefaultProfile**: Settings that apply to any profile that doesn't have explicit settings
+
+!!! important
+ DefaultPlatform and DefaultProfile settings are not additive. For example:
+ ```yaml
+ OverrideCompileFlags:
+ DefaultPlatform:
+ DefaultProfile:
+ Flags: "-Wall"
+ "g++":
+ Flags: "-O2"
+ ```
+ When using g++, only `-O2` will be used.
+ When using any other profile, only `-Wall` will be used, not `-Wall -O2`.
+
+??? TODO
+ If you have a setting that **only** has DefaultPlatform and DefaultProfile, you can directly
+ specify the settings without listing it under DefaultPlatform and DefaultProfile.
+
+ For example:
+ ```yaml
+ OverrideCompileFlags:
+ Flags: "-Wall"
+ ```
+ is equivalent to:
+ ```yaml
+ OverrideCompileFlags:
+ DefaultPlatform:
+ DefaultProfile:
+ Flags: "-Wall"
+ ```
diff --git a/mkdocs/docs/guides/building_project_sources.md b/mkdocs/docs/guides/building_project_sources.md
new file mode 100644
index 0000000..bc6648b
--- /dev/null
+++ b/mkdocs/docs/guides/building_project_sources.md
@@ -0,0 +1,254 @@
+# Building Project Sources
+
+## Specifying Build Type
+
+The `BuildType` setting specifies what type of output to build. There are four supported types:
+
+- **Executable**: Build as an executable program (default)
+- **Static**: Build as a static library
+- **Shared**: Build as a shared library
+- **Objects**: Only compile to object files without linking
+
+???+ example
+ ```yaml
+ # Build as a static library
+ BuildType: Static
+ ```
+
+!!! note
+ If not specified, the default build type is Executable.
+
+---
+
+## Editing Compile And Link Flags
+
+You can modify compile and link flags using `OverrideCompileFlags` and `OverrideLinkFlags`.
+Each setting supports two operations:
+
+- `Remove`: Remove flags from the default flags
+- `Append`: Add additional flags after the default flags
+
+???+ example
+ ```yaml
+ OverrideCompileFlags:
+ Windows:
+ "msvc":
+ Remove: "/W3" # Remove default warning level
+ Append: "/W4 /WX" # Use W4 and treat warnings as errors
+ DefaultPlatform:
+ "g++":
+ Append: "-Wall -Wextra -Werror"
+
+ OverrideLinkFlags:
+ Linux:
+ "g++":
+ Append: "-Wl,-rpath,\\$ORIGIN" # Add rpath for shared libraries
+ ```
+
+!!! warning
+ Flag modifications are passed directly to the shell. Be cautious when using variables or
+ user-provided input in your build commands.
+
+!!! note
+ The default flags for each profile can be found in your user config file.
+ Run `runcpp2 --show-config-path` to locate it.
+
+??? example "Common Use Cases"
+ ```yaml
+ OverrideCompileFlags:
+ DefaultPlatform:
+ "g++":
+ Append: "-O3" # Optimize for speed
+ "msvc":
+ Append: "/O2" # Optimize for speed
+
+ OverrideLinkFlags:
+ Windows:
+ "msvc":
+ Append: "/SUBSYSTEM:WINDOWS" # Build as GUI application
+ ```
+
+---
+
+## Adding Source Files And Include Paths
+
+You can add additional source files and include paths using `OtherFilesToBeCompiled` and `IncludePaths`.
+All paths are relative to the script file's location.
+
+???+ example
+ ```text title="Project Structure"
+ project/
+ ├── main.cpp
+ ├── src/
+ │ └── utils.cpp
+ │ └── helper.cpp
+ └── include/
+ └── utils.hpp
+ └── helper.hpp
+ ```
+
+ ```yaml title="Build Settings"
+ OtherFilesToBeCompiled:
+ DefaultPlatform:
+ DefaultProfile:
+ - "./src/utils.cpp"
+ - "./src/helper.cpp"
+ IncludePaths:
+ DefaultPlatform:
+ DefaultProfile:
+ - "./include"
+ ```
+
+!!! note
+ You can specify different source files for different platforms/profiles:
+ ```yaml
+ OtherFilesToBeCompiled:
+ Windows:
+ "msvc":
+ - "./src/windows_impl.cpp"
+ Unix:
+ "g++":
+ - "./src/unix_impl.cpp"
+ ```
+
+### Globbing Source Files
+
+**WIP**
+
+### Mixing C And C++ Files
+
+When building a project with a mixture of c and c++ files, the same profile will be used for all files.
+
+!!! note
+ This is different from other build systems like CMake where it will use the c compiler for c
+ files and the c++ compiler for c++ files.
+
+ ??? TODO
+ If you need the same behavior, you will need to create a script file for building the c files as if it is a standalone library first
+
+ ```text title="Project Structure"
+ project/
+ ├── main.cpp
+ ├── main.yaml
+ ├── src/
+ │ └── utils.c
+ │ └── math.c
+ │ └── helper.cpp
+ └── include/
+ └── utils.h
+ └── math.h
+ └── helper.hpp
+ ```
+
+ ```c title="src/utils.c"
+ /*runcpp2
+ Language: "c"
+ RequiredProfiles:
+ DefaultPlatform: ["gcc"]
+ OtherFilesToBeCompiled:
+ DefaultPlatform:
+ DefaultProfile:
+ - "./math.c"
+ IncludePaths:
+ DefaultPlatform:
+ DefaultProfile:
+ - "../include"
+ */
+ #include "utils.h"
+ int add(int a, int b) { return a + b; }
+ ```
+
+ ??? TODO
+ If the original utils.c or math.c is modified, the build will not be triggered. Have the option to use symlink for the contents of the local directory.
+
+ ```yaml title="main.yaml"
+ Dependencies:
+ - Name: "utils"
+ Source:
+ Local:
+ Path: "./src"
+ LibraryType: "Static"
+ IncludePaths:
+ - "./include"
+ Build:
+ DefaultPlatform:
+ DefaultProfile:
+ - "runcpp2 -b ./utils.c"
+ LinkProperties:
+ DefaultPlatform:
+ DefaultProfile:
+ SearchLibraryNames: ["utils"]
+ SearchDirectories: ["./"]
+ ```
+
+---
+
+## Adding Defines
+
+You can add preprocessor definitions using the `Defines` setting. Defines can be specified with or
+without values:
+
+???+ example
+ ```yaml
+ Defines:
+ DefaultPlatform:
+ DefaultProfile:
+ - "DEBUG" # Define without value (#define DEBUG)
+ - "VERSION_MAJOR=1" # Define with value (#define VERSION_MAJOR 1)
+ - "APP_NAME=\"MyApp\"" # Define with string value (#define APP_NAME "MyApp")
+ ```
+
+---
+
+## Adding Command Hooks
+
+runcpp2 provides four types of command hooks that run at different stages of the build:
+
+1. **Setup**: Run once before the script is first built
+ - Runs at the script's location when no build directory exists
+ - Useful for one-time initialization
+
+2. **PreBuild**: Run before each build
+ - Runs in the build directory before compilation starts
+ - Useful for generating files or updating dependencies
+
+3. **PostBuild**: Run after each successful build
+ - Runs in the output directory where binaries are located
+ - Useful for copying resources or post-processing binaries
+
+4. **Cleanup**: Run when using the `--cleanup` option
+ - Runs at the script's location before the build directory is removed
+ - Useful for cleaning up generated files
+
+???+ example
+ ```yaml
+ Setup:
+ Windows:
+ DefaultProfile:
+ - "echo Setting up in %cd%"
+ - "mkdir assets"
+
+ PreBuild:
+ DefaultPlatform:
+ DefaultProfile:
+ - "python generate_version.py" # Generate version header
+
+ PostBuild:
+ DefaultPlatform:
+ DefaultProfile:
+ - "cp -r assets/* ." # Copy assets to output
+
+ Cleanup:
+ DefaultPlatform:
+ DefaultProfile:
+ - "rm -rf assets" # Clean up generated files
+ ```
+
+!!! warning
+ All commands are passed directly to the shell. Be cautious when using variables or
+ user-provided input in your commands.
+
+---
+
+## Intellisense and language server support
+**WIP**
diff --git a/mkdocs/docs/guides/external_dependencies.md b/mkdocs/docs/guides/external_dependencies.md
new file mode 100644
index 0000000..a4181d6
--- /dev/null
+++ b/mkdocs/docs/guides/external_dependencies.md
@@ -0,0 +1,296 @@
+# External Dependencies
+
+## Adding External Dependencies
+
+runcpp2 supports external dependencies out of the box.
+
+You can specify the dependencies under the `Dependencies` section.
+
+Each dependency must have the following fields, other fields are optional:
+
+!!! note "Note: Dependencies that are imported (explained later) only need the `Source` field."
+
+
+- **Name**: The name of the dependency
+- **Platforms**: The platforms the dependency is supported on
+- **Source**: The source of the dependency
+- **LibraryType**: The type of the library (`Static`, `Object`, `Shared`, `Header`)
+
+---
+
+## Specifying Dependency Source
+
+In order to use a dependency, it must be coming from somewhere.
+
+This is configured under the `Source` section. We currently support 2 sources:
+
+- **Git Repository**: The dependency is cloned from a git repository
+- **Local Directory**: The dependency is copied from a local directory
+
+???+ example
+ ```yaml title="Git Dependency"
+ Dependencies:
+ - Name: MyLibrary
+ Platforms: [Windows, Linux, MacOS]
+ Source:
+ Git:
+ URL: "https://github.com/MyUser/MyLibrary.git"
+ LibraryType: Static
+ IncludePaths:
+ - "include/MyLibrary"
+ ```
+
+ ```yaml title="Local Dependency"
+ Dependencies:
+ - Name: LocalLibrary
+ Platforms: [Windows, Linux, MacOS]
+ Source:
+ Local:
+ Path: "./libs/LocalLibrary"
+ LibraryType: Static
+ IncludePaths:
+ - "include/LocalLibrary"
+ ```
+
+---
+
+## Adding Include Paths And Link Settings
+
+### Include Paths
+
+Include paths can be specified using the `IncludePaths` field. These paths are relative to the dependency's root directory:
+
+???+ example
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ # ... other fields ...
+ IncludePaths:
+ - "include" # MyLibrary/include
+ - "src/include" # MyLibrary/src/include
+ - "external/json/single_include"
+ ```
+
+### Link Settings
+
+For non-header libraries, you need to specify how to link against the library using `LinkProperties`:
+
+???+ example "Basic Link Settings"
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ LibraryType: Static
+ LinkProperties:
+ DefaultPlatform:
+ "g++":
+ # Names to search for when looking for library files
+ SearchLibraryNames: ["MyLibrary"]
+ # Where to look for the library files
+ SearchDirectories: ["build"]
+ # ... other fields ...
+ ```
+
+??? example "Platform-Specific Link Settings"
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ LibraryType: Shared
+ LinkProperties:
+ Windows:
+ "msvc":
+ SearchLibraryNames: ["MyLibrary"]
+ SearchDirectories: ["build/Release"]
+ # Additional linker flags
+ AdditionalLinkOptions: ["/SUBSYSTEM:WINDOWS"]
+ Linux:
+ "g++":
+ SearchLibraryNames: ["libMyLibrary"]
+ SearchDirectories: ["build"]
+ AdditionalLinkOptions: ["-pthread"]
+ # ... other fields ...
+ ```
+
+!!! tip "Library Name Patterns"
+ - The library name should be specified without extensions
+ - For Windows: `MyLibrary` will match `MyLibrary.lib` and `MyLibrary.dll`
+ - For Unix: `MyLibrary` will match `libMyLibrary.a` and `libMyLibrary.so`
+
+### Excluding Libraries
+
+Sometimes a dependency might have multiple library files, but you only want to link against specific ones.
+
+Use `ExcludeLibraryNames` to skip certain libraries:
+
+???+ example
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ LibraryType: Static
+ LinkProperties:
+ DefaultPlatform:
+ "g++":
+ SearchLibraryNames: ["MyLibrary"]
+ # Don't link against debug or test libraries
+ ExcludeLibraryNames: ["MyLibrary-d", "MyLibrary-test"]
+ SearchDirectories: ["build"]
+ # ... other fields ...
+ ```
+
+---
+
+## Adding Setup, Build and Cleanup Commands
+
+runcpp2 supports external dependencies with any build systems by allowing you to specify different command hooks similar to [command hooks in your project](building_project_sources.md#adding-command-hooks)
+
+The only difference is that `PreBuild` and `PostBuild` hooks are replaced with `Build` hook which is run together when building your project source files.
+
+??? example
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ # ... other fields ...
+ Setup:
+ DefaultPlatform:
+ "g++":
+ - "mkdir build"
+ Build:
+ DefaultPlatform:
+ "g++":
+ - "cmake --build build"
+ Cleanup:
+ DefaultPlatform:
+ "g++":
+ - "rm -rf build"
+ ```
+
+---
+
+## Copying Files
+
+Sometimes dependencies need additional files (like DLLs, shaders, or assets) to be copied next to your executable. You can specify these files using the `FilesToCopy` field.
+
+All paths are relative to the dependency's root directory. The files are copied to the output directory where the executable is located.
+
+???+ example "Basic File Copying"
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ # ... other fields ...
+ FilesToCopy:
+ DefaultPlatform:
+ DefaultProfile:
+ - "assets/shaders/default.glsl" # Copy shader file
+ - "data/config.json" # Copy config file
+ ```
+
+??? example "Copying Platform-Specific Files"
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ # ... other fields ...
+ FilesToCopy:
+ Windows:
+ "msvc":
+ - "assets/fonts/windows.ttf" # Windows-specific font
+ Linux:
+ "g++":
+ - "assets/fonts/linux.ttf" # Linux-specific font
+ ```
+
+---
+
+## Importing Dependency Info
+
+You can separate dependency info into standalone YAML files and import them into your project.
+
+The standalone YAML file is the same as a single dependency entry in the `Dependencies` section.
+
+??? example
+ If you have:
+ ```yaml
+ Dependencies:
+ - Name: MyLibrary
+ Platforms: [Windows, Linux, MacOS]
+ Source:
+ Git:
+ URL: "https://github.com/MyUser/MyLibrary.git"
+ LibraryType: Header
+ ```
+ Then you can create a standalone YAML file:
+ ```yaml
+ Name: MyLibrary
+ Platforms: [Windows, Linux, MacOS]
+ Source:
+ Git:
+ URL: "https://github.com/MyUser/MyLibrary.git"
+ LibraryType: Header
+ ```
+
+To import a dependency info, use the `ImportPath` field under the `Source` section:
+
+Just like previously, you can import the dependency info from a git repository or a local directory.
+
+When using `ImportPath`:
+
+- For Git sources: `ImportPath` is relative to the git repository root
+- For Local sources: `ImportPath` is relative to the `Path` specified under `Local`
+- If neither Git nor Local source is specified, `ImportPath` is relative to the script directory
+
+!!! note
+ When using `ImportPath`, Any fields in the dependency entry are not needed and will be ignored.
+
+???+ example "Importing from a Git Repository"
+ ```text title="Remote Git Repository Structure"
+ project/
+ ├── src/
+ │ └── (source files...)
+ └── config/
+ └── build_info.yaml
+ ```
+
+ ```yaml title="Build Settings In Your Project"
+ Dependencies:
+ - Source:
+ ImportPath: "config/build_info.yaml"
+ Git:
+ URL: "https://github.com/MyUser/MyLibrary.git"
+ ```
+
+???+ example "Importing from a Local Directory"
+ ```text title="Local Directory Structure"
+ project/
+ ├── main.yaml
+ ├── main.cpp
+ ├── libs/
+ │ └── LocalLibrary/
+ │ ├── (source files...)
+ │ └── config/
+ │ └── build_info.yaml
+ └── src/
+ └── (source files...)
+ ```
+
+ ```yaml title="main.yaml"
+ Dependencies:
+ - Source:
+ ImportPath: "config/build_info.yaml"
+ Local:
+ # NOTE: This can be an absolute path
+ Path: "./libs/LocalLibrary"
+ ```
+
+
+
+Example of a dependency configuration file (dependency.yaml):
+```yaml
+Name: ImportedLibrary
+Platforms: [Windows, Linux, MacOS]
+LibraryType: Static
+IncludePaths:
+- "src/include"
+Build:
+ DefaultPlatform:
+ "g++":
+ - "cmake -B build"
+ - "cmake --build build"
+```
diff --git a/mkdocs/docs/guides/scriptable_pipeline.md b/mkdocs/docs/guides/scriptable_pipeline.md
new file mode 100644
index 0000000..1e0ab34
--- /dev/null
+++ b/mkdocs/docs/guides/scriptable_pipeline.md
@@ -0,0 +1,3 @@
+# Scriptable Pipeline
+
+**WIP**
\ No newline at end of file
diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md
new file mode 100644
index 0000000..c2ca090
--- /dev/null
+++ b/mkdocs/docs/index.md
@@ -0,0 +1,120 @@
+# Home
+
+
+
+runcpp2 is a simple declarable, scriptable, flexible cross-platform build system build system for c or c++
+
+- 🚀 **Simple**: `#!shell runcpp2 main.cpp`, this is all you need to get started
+- 📝 **Declarable**: *Quick, Concise, Minimal* YAML format
+- 🔧 **Scriptable**: *Customize, Run And Debug* your build pipeline with c++, or just use it as a script.
+ No longer need to juggle between CMake, Python, Bash, Batch, Lua, etc...
+- 🪜 **Flexible**: *YAML* for small project, *c++* for finer control
+
+
+## 🛠️ Prerequisites
+- Any c or c++ compiler. The default user config only has g++ and msvc profiles. But feel free to
+add other compilers.
+
+## 📥️ Installation
+You can either build from source or use the binary release
+
+Binary Release (Only Linux and Windows for now):
+[https://github.com/Neko-Box-Coder/runcpp2/releases](https://github.com/Neko-Box-Coder/runcpp2/releases)
+
+
+Finally, you just need to add runcpp2 binary location to the `PATH` environment variable and
+you can run c++ files anywhere you want.
+
+## ⚡️ Getting Started
+
+### 1. Running source file directly
+Suppose you have a c++ file called `script.cpp`, you can run it immediately by doing
+
+```shell
+runcpp2 ./script.cpp
+```
+
+??? example
+ ```cpp title="script.cpp"
+ #include
+ int main(int argc, char** argv)
+ {
+ if(argc != 2)
+ {
+ std::cout << "Usage: runcpp2 ./script.cpp "
+ return 1;
+ }
+
+ std::cout << "Hello " << argv[1] << std::endl;
+ return 0;
+ }
+ ```
+
+!!! note
+ On Unix, if you have added runcpp2 to your PATH and add this line `//bin/true;runcpp2 "$0" "$@"; exit $?;`
+ to the top of your script, you can run the script directly by `./script.cpp `
+
+ ??? example
+ ```cpp title="script.cpp"
+ //bin/true;runcpp2 "$0" "$@"; exit $?;
+ #include
+ int main(int, char**) { std::cout << "Hello World" << std::endl; }
+ ```
+
+---
+
+### 2. Watch and give compile errors
+If you want to edit the script but want to have feedback for any error, you can use "watch" mode.
+
+```shell title="shell"
+runcpp2 --watch ./script.cpp
+```
+
+---
+
+### 3. Sepcifying Build Settings
+Build settings such as compile/link flags, external dependencies, command hooks, etc.
+can be spcified inlined inside a source file or as a separate yaml file in the format of YAML
+
+- To specify build settings in a dedicated yaml file:
+ - The yaml file in the same directory and share the same as the source file being run will be used
+- To specify inline build settings inside a source file:
+ - Put them inside a comment with `runcpp2` at the beginning of the build settings
+ - The inline build settings can exist in anywhere of the source file
+ - Both inline (but continuous) comments (`#!cpp //`) and block comments are supported (`#!cpp /* */`)
+
+??? example "Example Inline Build Settings"
+ ```cpp title="script.cpp"
+ /*runcpp2
+ OverrideCompileFlags:
+ DefaultPlatform:
+ "g++":
+ Append: "-Wfloat-equal -Wextra"
+ */
+ int main(int, char**) { float a = 1.f; float b = 1.f; return a == b ? 0 : 1; }
+ ```
+ ```shell title="shell"
+ runcpp2 script.cpp
+ ```
+
+??? example "Example Dedicated Build Settings"
+ ```yaml title="script.yaml"
+ OverrideCompileFlags:
+ DefaultPlatform:
+ "g++":
+ Append: "-Wfloat-equal -Wextra"
+ ```
+ ```cpp title="script.cpp"
+ int main(int, char**) { float a = 1.f; float b = 1.f; return a == b ? 0 : 1; }
+ ```
+ ```shell title="shell"
+ runcpp2 script.cpp
+ ```
+
+For a complete list of build settings, see [Build Settings](build_settings.md) or generate the template with
+```shell
+runcpp2 --create-script-template ./script.cpp # Embeds the build settings template as comment
+runcpp2 --create-script-template ./script.yaml # Creates the build settings template as dedicated yaml file
+runcpp2 -t ./script.cpp # Short form
+```
+
diff --git a/mkdocs/docs/program_manual.md b/mkdocs/docs/program_manual.md
new file mode 100644
index 0000000..ef6cd9d
--- /dev/null
+++ b/mkdocs/docs/program_manual.md
@@ -0,0 +1,30 @@
+# Program Manual
+
+## Usage
+`#!shell runcpp2 [options] [input_file]`
+
+## Options
+```text
+Run/Build:
+ -b, --[b]uild Build the script and copy output files to the working directory
+ -w, --[w]atch Watch script changes and output any compiling errors
+ -l, --[l]ocal Build in the current working directory under .runcpp2 directory
+ -e, --[e]xecutable Runs as executable instead of shared library
+ -c, --[c]onfig Use specified config file instead of default
+ -t, --create-script-[t]emplate Creates/prepend runcpp2 script info template
+ -s, --build-[s]ource-only (Re)Builds source files only without building dependencies.
+ The previous built binaries will be used for dependencies.
+ Requires dependencies to be built already.
+Reset/Cleanup:
+ -rc, --[r]eset-[c]ache Deletes compiled source files cache only
+ -ru, --[r]eset-[u]ser-config Replace current user config with the default one
+ -rd, --[r]eset-[d]ependencies Reset dependencies (comma-separated names, or "all" for all)
+ -cu, --[c]lean[u]p Run cleanup commands and remove build directory
+Settings:
+ -sc, --[s]how-[c]onfig-path Show where runcpp2 is reading the config from
+ -v, --[v]ersion Show the version of runcpp2
+ -h, --[h]elp Show this help message
+ --log-level Sets the log level (Normal, Info, Debug) for runcpp2.
+```
+
+
diff --git a/mkdocs/docs/user_config.md b/mkdocs/docs/user_config.md
new file mode 100644
index 0000000..da05eb2
--- /dev/null
+++ b/mkdocs/docs/user_config.md
@@ -0,0 +1,443 @@
+# User Config
+
+**TODO**
+
+## Default
+```yaml
+# List of anchors that will be aliased later
+Templates:
+ MSVC_CompileFlags: &MSVC_CompileFlags
+ Flags: "/nologo /W4 /diagnostics:caret /D NDEBUG /utf-8 /Gm- /MD /EHa /TP /std:c++17 /GR /TP"
+
+ "g++_CompileRunParts": &g++_CompileRunParts
+ - Type: Once
+ CommandPart: "{Executable} -c {CompileFlags}"
+ - Type: Repeats
+ CommandPart: " -D{DefineNameOnly}="
+ - Type: Repeats
+ CommandPart: " \"-D{DefineName}={DefineValue}\""
+ - Type: Repeats
+ CommandPart: " -I\"{IncludeDirectoryPath}\""
+ - Type: Once
+ CommandPart: " \"{InputFilePath}\" -o \"{OutputFileDirectory}{/}{ObjectLinkFile.Prefix}{InputFileName}{ObjectLinkFile.Extension}\""
+
+ "g++_CompileExpectedOutputFiles": &g++_CompileExpectedOutputFiles
+ - "{OutputFileDirectory}{/}{ObjectLinkFile.Prefix}{InputFileName}{ObjectLinkFile.Extension}"
+
+ "vs2022_v17+_CompileRunParts": &vs2022_v17+_CompileRunParts
+ - Type: Once
+ CommandPart: "{Executable} /c {CompileFlags}"
+ - Type: Repeats
+ CommandPart: " /D{DefineNameOnly}="
+ - Type: Repeats
+ CommandPart: " \"/D{DefineName}={DefineValue}\""
+ - Type: Repeats
+ CommandPart: " /I\"{IncludeDirectoryPath}\""
+ - Type: Once
+ CommandPart: " /Fo\"{OutputFileDirectory}{/}{ObjectLinkFile.Prefix}{InputFileName}{ObjectLinkFile.Extension}\" \"{InputFilePath}\""
+
+ "vs2022_v17+_CompileExpectedOutputFiles": &vs2022_v17+_CompileExpectedOutputFiles
+ - "{OutputFileDirectory}{/}{ObjectLinkFile.Prefix}{InputFileName}{ObjectLinkFile.Extension}"
+
+ # The following fields set the prefixes and extensions for each type of the files
+ # If the name of an object files are libtest.so and libtest2.so,
+ # the prefixes and extensions are "lib" and ".so"
+
+ # TODO: Add support for custom platform
+ # Each of the platform dependent settings can be listed under
+ # - DefaultPlatform
+ # - Windows
+ # - Linux
+ # - MacOS
+ # - Unix
+ FilesTypes: &CommonFilesTypes
+ # The file properties for the files to be **linked** as object file for each platform
+ ObjectLinkFile:
+ Prefix:
+ DefaultPlatform: ""
+ Extension:
+ Windows: ".obj"
+ Unix: ".o"
+
+ # The file properties for the files to be **linked** as shared libraries for each platform
+ SharedLinkFile:
+ Prefix:
+ Windows: ""
+ Linux: "lib"
+ MacOS: ""
+ Extension:
+ Windows: ".lib"
+ Linux: ".so"
+ MacOS: ".dylib"
+
+ # The file properties for the files to be **copied** as shared libraries for each platform
+ SharedLibraryFile:
+ Prefix:
+ Windows: ""
+ Linux: "lib"
+ MacOS: ""
+ Extension:
+ Windows: ".dll"
+ Linux: ".so"
+ MacOS: ".dylib"
+
+ # The file properties for the files to be linked as static libraries for each platform
+ StaticLinkFile:
+ Prefix:
+ Unix: "lib"
+ Windows: ""
+ Extension:
+ Windows: ".lib"
+ Unix: ".a"
+
+ # (Optional) The file properties for debug symbols to be copied alongside the binary
+ # for each platform
+ DebugSymbolFile:
+ Prefix:
+ Windows: ""
+ Unix: ""
+ Extension:
+ Windows: ""
+ Unix: ""
+
+# WARNING: All command substitutions in this file are passed directly to the shell.
+# Exercise caution when using variables or user-provided input in your build commands
+# to prevent potential security vulnerabilities.
+
+# A profile to be used if not specified while running the build script
+PreferredProfile: "g++"
+
+# List of compiler/linker profiles that instruct how to compile/link
+Profiles:
+ # Name (case sensitive) of the profile that can be queried from a script
+- Name: "g++"
+
+ # (Optional) Name aliases (case sensitive) of the current profile
+ NameAliases: ["mingw"]
+
+ # The file extensions associated with the profile
+ FileExtensions: [.cpp, .cc, .cxx]
+
+ # The languages supported by the profile
+ Languages: ["c++"]
+
+ # (Optional) The commands to run in **shell** before calling the compiler/linker for each platform.
+ # This is run inside the root build directory.
+ # Setup:
+ # DefaultPlatform: []
+
+ # (Optional) The commands to run in **shell** after calling the compiler/linker for each platform.
+ # This is run inside the root build directory.
+ # Cleanup:
+ # DefaultPlatform: []
+
+ # The file properties for the object files for each platform.
+ FilesTypes: *CommonFilesTypes
+
+ # Specify the compiler settings
+ Compiler:
+ # (Optional) The command to be prepend for each compile command in **shell** for each platform
+ # PreRun:
+ # DefaultPlatform: ""
+
+ # Shell command to use for checking if the executable exists or not
+ CheckExistence:
+ DefaultPlatform: "g++ -v"
+
+ # Here are a list of substitution strings for RunParts, Setup and Cleanup.
+ # To escape '{' and '}' to avoid substitutioon, simply repeat the '{' or '}' character again.
+ # So "${MyBashVariable}" will become "${{MyBashVariable}}"
+
+ # {Executable}: Compiler executable
+ # {CompileFlags}: Compile flags from config and override
+ # {InputFileName}: Name of the input file (without directory path and extension)
+ # {InputFileExtension}: Extension of the input file
+ # {InputFileDirectory}: Directory of the input file
+ # {InputFilePath}: Full path to the input file
+ # {OutputFileDirectory}: Directory of all the output files
+ # {/}: Filesystem separator for the host platform
+
+ # {SharedLibraryFile.Prefix}
+ # {SharedLinkFile.Prefix}
+ # {StaticLinkFile.Prefix}
+ # {ObjectLinkFile.Prefix}
+ # {DebugSymbolFile.Prefix}
+
+ # {SharedLibraryFile.Extension}
+ # {SharedLinkFile.Extension}
+ # {StaticLinkFile.Extension}
+ # {ObjectLinkFile.Extension}
+ # {DebugSymbolFile.Extension}
+
+ # Below are iterable substitution strings, must be inside "Repeats" run type:
+ # {IncludeDirectoryPath}: Path to all the include directories
+ # {DefineNameOnly}: All the defines without a value specified (equivalent to #define X)
+ # {DefineName}: Name of all the defines that has a value specified
+ # {DefineValue}: Value of all the defines that has a value specified (use together with {DefineName})
+ CompileTypes:
+ Executable:
+ DefaultPlatform:
+ # Default flags to be substituted as {CompileFlags}
+ Flags: "-std=c++17 -Wall -g"
+
+ # The executable to be substituted as {Executable}
+ Executable: "g++"
+
+ # The components for the command to be run
+ RunParts: *g++_CompileRunParts
+
+ # What files to be expected as output for the command
+ ExpectedOutputFiles: *g++_CompileExpectedOutputFiles
+
+ # (Optional) The commands to run in **shell** BEFORE compiling
+ # This is run inside the .runcpp2 directory where the build happens.
+ # Setup: []
+
+ # (Optional) The commands to run in **shell** AFTER compiling
+ # This is run inside the .runcpp2 directory where the build happens.
+ # Cleanup: []
+ ExecutableShared:
+ DefaultPlatform:
+ Flags: "-std=c++17 -Wall -g -fpic"
+ Executable: "g++"
+ RunParts: *g++_CompileRunParts
+ ExpectedOutputFiles: *g++_CompileExpectedOutputFiles
+ # Setup: []
+ # Cleanup: []
+ Static:
+ DefaultPlatform:
+ Flags: "-std=c++17 -Wall -g"
+ Executable: "g++"
+ RunParts: *g++_CompileRunParts
+ ExpectedOutputFiles: *g++_CompileExpectedOutputFiles
+ # Setup: []
+ # Cleanup: []
+ Shared:
+ DefaultPlatform:
+ Flags: "-std=c++17 -Wall -g -fpic"
+ Executable: "g++"
+ RunParts: *g++_CompileRunParts
+ ExpectedOutputFiles: *g++_CompileExpectedOutputFiles
+ # Setup: []
+ # Cleanup: []
+
+ # Specify the linker settings
+ Linker:
+ CheckExistence:
+ DefaultPlatform: "g++ -v"
+
+ # Here are a list of substitution strings for RunParts, Setup and Cleanup
+ # {Executable}: Linker executable
+ # {LinkFlags}: Link flags from config and override
+ # {OutputFileName}: Name of all the output files (without directory path and extension)
+ # {OutputFileDirectory}: Directory of all the output files
+ # {/}: Filesystem separator for the host platform
+
+ # {SharedLibraryFile.Prefix}
+ # {SharedLinkFile.Prefix}
+ # {StaticLinkFile.Prefix}
+ # {ObjectLinkFile.Prefix}
+ # {DebugSymbolFile.Prefix}
+
+ # {SharedLibraryFile.Extension}
+ # {SharedLinkFile.Extension}
+ # {StaticLinkFile.Extension}
+ # {ObjectLinkFile.Extension}
+ # {DebugSymbolFile.Extension}
+
+ # Below are iterable substitution strings, must be inside "Repeats" run type:
+ # {LinkFileName}: Name of the file to be linked, regardless of the build type
+ # {LinkFileExtension}: File Extension of the file to be linked, regardless of the build type
+ # {LinkFileDirectory}: Directory of the file to be linked, regardless of the build type
+ # {LinkFilePath}: Full path to the file to be linked, regardless of the build type
+
+ # {LinkObjectFileName}: Name of the object file to be linked
+ # {LinkObjectFileExtension}: File Extension of the object file to be linked
+ # {LinkObjectFileDirectory}: Directory of the object file to be linked
+ # {LinkObjectFilePath}: Full path to the object file to be linked
+
+ # {LinkSharedFileName}: Name of the shared file to be linked
+ # {LinkSharedFileExtension}: File Extension of the shared file to be linked
+ # {LinkSharedFileDirectory}: Directory of the shared file to be linked
+ # {LinkSharedFilePath}: Full path to the shared file to be linked
+
+ # {LinkStaticFileName}: Name of the static file to be linked
+ # {LinkStaticFileExtension}: File Extension of the static file to be linked
+ # {LinkStaticFileDirectory}: Directory of the static file to be linked
+ # {LinkStaticFilePath}: Full path to the static file to be linked
+ LinkTypes:
+ Executable:
+ Unix:
+ Flags: "-Wl,-rpath,\\$ORIGIN"
+ Executable: "g++"
+ RunParts:
+ - Type: Once
+ CommandPart: "{Executable} {LinkFlags} -o \"{OutputFileDirectory}{/}{OutputFileName}\""
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{OutputFileName}"]
+ # Setup: []
+ # Cleanup: []
+ Windows:
+ Flags: "-Wl,-rpath,\\$ORIGIN"
+ Executable: "g++"
+ RunParts:
+ - Type: Once
+ CommandPart: "{Executable} {LinkFlags} -o \"{OutputFileDirectory}{/}{OutputFileName}.exe\""
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{OutputFileName}.exe"]
+ # Setup: []
+ # Cleanup: []
+ ExecutableShared:
+ DefaultPlatform:
+ Flags: "-shared -Wl,-rpath,\\$ORIGIN"
+ Executable: "g++"
+ RunParts:
+ - Type: Once
+ CommandPart: "{Executable} {LinkFlags} -o \"{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}\""
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"]
+ # Setup: []
+ # Cleanup: []
+ Static:
+ DefaultPlatform:
+ Flags: ""
+ Executable: "g++"
+ RunParts:
+ - Type: Once
+ CommandPart: "{Executable} {LinkFlags} -o \"{OutputFileDirectory}{/}{StaticLinkFile.Prefix}{OutputFileName}{StaticLinkFile.Extension}\""
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{StaticLinkFile.Prefix}{OutputFileName}{StaticLinkFile.Extension}"]
+ # Setup: []
+ # Cleanup: []
+ Shared:
+ DefaultPlatform:
+ Flags: "-shared -Wl,-rpath,\\$ORIGIN"
+ Executable: "g++"
+ RunParts:
+ - Type: Once
+ CommandPart: "{Executable} {LinkFlags} -o \"{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}\""
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"]
+ # Setup: []
+ # Cleanup: []
+
+# https://learn.microsoft.com/en-us/cpp/overview/compiler-versions?view=msvc-170
+- Name: "vs2022_v17+"
+ NameAliases: ["msvc1930+", "msvc"]
+ Languages: ["c++"]
+ FileExtensions: [.cpp, .cc, .cxx]
+ FilesTypes: *CommonFilesTypes
+ Setup:
+ Windows:
+ - >-
+ for /f "usebackq tokens=*" %i in (`CALL "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe"
+ -version "[17.0,18.0)" -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do (
+ echo "%i\VC\Auxiliary\Build\vcvarsall.bat" x64 > .\prerun.bat
+ )
+ Cleanup:
+ Windows: [ "del .\\prerun.bat" ]
+ Compiler:
+ PreRun:
+ Windows: ".\\prerun.bat"
+ CheckExistence:
+ Windows: "where.exe CL.exe"
+ CompileTypes:
+ Executable:
+ Windows:
+ <<: *MSVC_CompileFlags
+ Executable: "CL.exe"
+ RunParts: *vs2022_v17+_CompileRunParts
+ ExpectedOutputFiles: *vs2022_v17+_CompileExpectedOutputFiles
+ ExecutableShared:
+ Windows:
+ <<: *MSVC_CompileFlags
+ Executable: "CL.exe"
+ RunParts: *vs2022_v17+_CompileRunParts
+ ExpectedOutputFiles: *vs2022_v17+_CompileExpectedOutputFiles
+ Static:
+ Windows:
+ <<: *MSVC_CompileFlags
+ Executable: "CL.exe"
+ RunParts: *vs2022_v17+_CompileRunParts
+ ExpectedOutputFiles: *vs2022_v17+_CompileExpectedOutputFiles
+ Shared:
+ Windows:
+ <<: *MSVC_CompileFlags
+ Executable: "CL.exe"
+ RunParts: *vs2022_v17+_CompileRunParts
+ ExpectedOutputFiles: *vs2022_v17+_CompileExpectedOutputFiles
+ Linker:
+ PreRun:
+ Windows: ".\\prerun.bat"
+ CheckExistence:
+ Windows: "where.exe link.exe"
+ LinkTypes:
+ Executable:
+ Windows:
+ Flags: >-
+ /NOLOGO kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib
+ oleaut32.lib uuid.lib comdlg32.lib advapi32.lib /manifest:embed /SUBSYSTEM:CONSOLE
+ Executable: "link.exe"
+ RunParts:
+ - Type: Once
+ CommandPart: >-
+ {Executable} {LinkFlags}
+ /OUT:"{OutputFileDirectory}{/}{OutputFileName}.exe"
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{OutputFileName}.exe"]
+ ExecutableShared:
+ Windows:
+ Flags: >-
+ /NOLOGO kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib
+ oleaut32.lib uuid.lib comdlg32.lib advapi32.lib /manifest:embed /SUBSYSTEM:CONSOLE
+ /DLL
+ Executable: "link.exe"
+ RunParts:
+ - Type: Once
+ CommandPart: >-
+ {Executable} {LinkFlags}
+ /OUT:"{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"
+ /IMPLIB:"{OutputFileDirectory}{/}{SharedLinkFile.Prefix}{OutputFileName}{SharedLinkFile.Extension}"
+ /DEF:".\temp.def"
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"]
+ Setup: [ "echo EXPORTS > .\\temp.def", "echo. main @1 >> .\\temp.def" ]
+ Cleanup: [ "del .\\temp.def" ]
+ Static:
+ Windows:
+ Flags: "/NOLOGO"
+ Executable: "lib.exe"
+ RunParts:
+ - Type: Once
+ CommandPart: >-
+ {Executable} {LinkFlags}
+ /OUT:"{OutputFileDirectory}{/}{StaticLinkFile.Prefix}{OutputFileName}{StaticLinkFile.Extension}"
+ /IMPLIB:"{OutputFileDirectory}{/}{SharedLinkFile.Prefix}{OutputFileName}{SharedLinkFile.Extension}"
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{StaticLinkFile.Prefix}{OutputFileName}{StaticLinkFile.Extension}"]
+ Shared:
+ Windows:
+ Flags: >-
+ /NOLOGO kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib
+ oleaut32.lib uuid.lib comdlg32.lib advapi32.lib /manifest:embed /SUBSYSTEM:CONSOLE
+ /DLL
+ Executable: "link.exe"
+ RunParts:
+ - Type: Once
+ CommandPart: >-
+ {Executable} {LinkFlags}
+ /OUT:"{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"
+ /IMPLIB:"{OutputFileDirectory}{/}{SharedLinkFile.Prefix}{OutputFileName}{SharedLinkFile.Extension}"
+ - Type: Repeats
+ CommandPart: " \"{LinkFilePath}\""
+ ExpectedOutputFiles: ["{OutputFileDirectory}{/}{SharedLibraryFile.Prefix}{OutputFileName}{SharedLibraryFile.Extension}"]
+
+```
diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml
new file mode 100644
index 0000000..6bbb8f4
--- /dev/null
+++ b/mkdocs/mkdocs.yml
@@ -0,0 +1,62 @@
+site_name: runcpp2
+site_url: 'https://neko-box-coder.github.io/runcpp2/'
+
+theme:
+ name: material
+ logo: Runcpp2Logo.png
+ favicon: favicon.png
+ palette:
+ - scheme: slate
+ primary: black
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+ - scheme: default
+ primary: black
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ features:
+ - toc.follow
+ - toc.integrate
+ - content.code.copy
+ - content.code.select
+ - navigation.sections
+ - navigation.expand
+ - navigation.tabs
+ - navigation.tabs.sticky
+
+nav:
+ - index.md
+ # - guides.md
+ - Guides:
+ - guides/basic_concepts.md
+ - guides/building_project_sources.md
+ - guides/external_dependencies.md
+ - guides/scriptable_pipeline.md
+ - program_manual.md
+ - build_settings.md
+ - user_config.md
+
+extra_css: [extra.css]
+markdown_extensions:
+- admonition
+# - attr_list
+# - material.extensions.preview:
+# targets:
+# include:
+# - "build_settings.md"
+- pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.details
+- pymdownx.superfences
+- toc:
+ toc_depth: 6
+
+extra:
+ version:
+ provider: mike