From 4ab46c6d9c557522d2a7fb8518ab0f5e38a4984a Mon Sep 17 00:00:00 2001 From: Neko Box Coder Date: Wed, 22 Jan 2025 23:02:07 +0000 Subject: [PATCH] Initial Documentations --- .gitignore | 2 +- DefaultYAMLs/DefaultScriptInfo.yaml | 2 +- README.md | 100 ++-- TODO.md | 8 +- mkdocs/docs/Runcpp2Logo.png | Bin 0 -> 3730 bytes mkdocs/docs/build_settings.md | 488 ++++++++++++++++++ mkdocs/docs/extra.css | 24 + mkdocs/docs/favicon.png | Bin 0 -> 1333 bytes mkdocs/docs/guides/basic_concepts.md | 117 +++++ .../docs/guides/building_project_sources.md | 254 +++++++++ mkdocs/docs/guides/external_dependencies.md | 296 +++++++++++ mkdocs/docs/guides/scriptable_pipeline.md | 3 + mkdocs/docs/index.md | 120 +++++ mkdocs/docs/program_manual.md | 30 ++ mkdocs/docs/user_config.md | 443 ++++++++++++++++ mkdocs/mkdocs.yml | 62 +++ 16 files changed, 1884 insertions(+), 65 deletions(-) create mode 100644 mkdocs/docs/Runcpp2Logo.png create mode 100644 mkdocs/docs/build_settings.md create mode 100644 mkdocs/docs/extra.css create mode 100644 mkdocs/docs/favicon.png create mode 100644 mkdocs/docs/guides/basic_concepts.md create mode 100644 mkdocs/docs/guides/building_project_sources.md create mode 100644 mkdocs/docs/guides/external_dependencies.md create mode 100644 mkdocs/docs/guides/scriptable_pipeline.md create mode 100644 mkdocs/docs/index.md create mode 100644 mkdocs/docs/program_manual.md create mode 100644 mkdocs/docs/user_config.md create mode 100644 mkdocs/mkdocs.yml 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 -![runcpp2 logo](./Runcpp2Logo.png) +![](./Runcpp2Logo.png) -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 0000000000000000000000000000000000000000..81a7cddf489626178e062786d2ef226f1eaaf0f1 GIT binary patch literal 3730 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 literal 0 HcmV?d00001 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 0000000000000000000000000000000000000000..cdf6820b2981cf33877cdc7608c0c14e043b9ebb GIT binary patch literal 1333 zcmV-51E5cq;%82PT@#A<3fXW7fF^bc!g+FBFH z6q}pNHs_p6(=9i1Ryaikw3fF1aJps2OxK&03q`pKrlqDb668goieXW3b$~Z^oF3>D zR){bMNCr^V8)D313v2!Mtc;So2C%T;Oomb2i!d}?zbal)b~#Mc+RfRcEB{r1oGtD| zTyg>!a{HlLsmcdFiOw&~9^KSi027olMi+Na96$z%$i^sb`C-xaQ!`MFxSzVra_eLM z&Py?|R^u;-8QXLGH=SDAn|q)<$9x!FH5R9 z`DX*Rb`HP>Efz5=lCGwI-&OrE5j@7+e{Ya@AYgH$u^F$o_4g;;=OXioRC1n4V{pHi z;3Fj%L?+p4AFN6}vpc8IJ@obfLE|AN%F*Wk?eVf|!(L`*e@NCl1swjdjDTffL`YAK zI;%M=CEX(FYJf);B_k3Zu!ojUek)$Q%g(jNA}#unKo&3TU&LbkE7@6 zLW7m^q>6_wh6jjX@o}*sZTG}R^YW~T%$YT*t>3nlQfcd zn=T(|&ri>w=vy~+H#`_4JUum?%vYw7n$o(VRh5c5FZ+tG@mr-QTnY>9HF=riz9Or= zvCAb;!0J%o(^C7Bw>}g1*{cjr>C32LDL5PkRi()r;E=n9pU&6Q(&=(iR8ezTuvgZ^ zpZfyI2wLQbOHf(wB|WwMK1fMQASEfGtv_Jd6klxMKuID_(03e z6ClGo2N{9n1Q#MgZIdtDBSb+PKsGpCF`IK=8_{?>;Sd0TMFs9Xg3Rmg;8tbziOQ!= zwb$e>$f)SaSm^vJhFl=rV=tUpz|Yt+V_?PDg}o7nFsD8z-@P1>b##3~RMBf9th_04 zpYO^X;_Z!amjD2Z3(mZ5i@jD<9_XlRD-A{{q=j``7musI6XA#e0B?PAwx1R7KZ`O> rFp9A+s#u5e=8wOONH1=T|Ec{0G%)s&#WoBM00000NkvXXu0mjfEXaq` literal 0 HcmV?d00001 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 + +![](./Runcpp2Logo.png) + +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