From dbee00d160c0df24314c77e094fdec52ff8b7459 Mon Sep 17 00:00:00 2001 From: Matthew Asplund Date: Sat, 1 Feb 2020 19:52:23 -0800 Subject: [PATCH] Add cli and architecture docs (#21) --- Docs/Architecture.md | 14 +++++++++++ Docs/CLI.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ Docs/Docs/Samples.md | 0 README.md | 2 ++ 4 files changed, 72 insertions(+) create mode 100644 Docs/Architecture.md create mode 100644 Docs/CLI.md delete mode 100644 Docs/Docs/Samples.md diff --git a/Docs/Architecture.md b/Docs/Architecture.md new file mode 100644 index 00000000..2b79121d --- /dev/null +++ b/Docs/Architecture.md @@ -0,0 +1,14 @@ +# Architecture +The internal architecture is still in flux, however the general concepts should remain unchanged. + +## Recipe +The Soup Recipe is a property bag defined in the [toml](https://github.com/toml-lang/toml) language. It contains a few special properties that will be used in the core build engine to recursively build all dependencies. The build engine will initialize the active build statue with a table named "Recipe" with all properties loaded from the file to grant access to the build extensions during execution. + +## Build Engine +Soup builds are fairly simple at their core. There are three phases. + +1) **Parse Recipe** - The Recipe toml file is read from disk. +2) **Build Dependencies** - The build engine recursively builds all transient dependencies. +3) **Build Extensions** - The build engine recursively builds all build extension DLLs. The engine will then invoke the "RegisterBuildExtension" method that is exported from the Extension DLL. +4) **Run Tasks** - The build engine will invoke all registered build tasks in their defined order (Note: this is still being worked on.) The Tasks can influence each other by reading and setting properties on the active state. A build task should not actually perform any commands itself, it will instead generate Build Commands which are self contained operation definitions with input/output files. +5) **Run Commands** - The final stage of the build is to execute the build commands that were generated from the build tasks. These commands contain the input and output files that will be used to perform incremental builds. (Note: There is currently a very simple time-stamp based incremental build that relies on the compiler to print all included files. There is an open question if this can be replaced with a better system that monitors the filesystem for changes, possibly BuildXL). diff --git a/Docs/CLI.md b/Docs/CLI.md new file mode 100644 index 00000000..75b432c2 --- /dev/null +++ b/Docs/CLI.md @@ -0,0 +1,56 @@ +# Command Line Interface (CLI) +Soup is at its core a command line application. The CLI is designed to be as clean and simple as possible while still allowing for easy execution of common build related tasks. + +``` +soup [arguments] +``` + +## Build +### Overview +Build a recipe and all transient dependencies. +``` +soup build [-flavor |-force] +``` + +`directory` - An optional parameter that directly follows the build command. If present this specifies the directory to look for a recipe file to build. If not present then the build command will use the current active directory. + +`-flavor ` - An optional parameter to specify the build flavor. Common values include `debug` or `release`. If not present the build will default to `release`. + +`-force` - An optional parameter that forces the build to ignore incremental state and rebuild the world. + +### Examples +Build a Recipe in the current directory for release. +``` +soup build +``` + +Build a debug Recipe in a different directory. +``` +soup build C:\Code\MyProject\ -flavor debug +``` + +## Init +### Overview +Initialize a new console application project in the current active directory. +``` +soup init +``` + +### Examples +The one and only way to use this command. +``` +soup init +``` + +## Version +### Overview +Print the version of the Soup executable. +``` +soup version +``` + +### Examples +The one and only way to use this command. +``` +soup version +``` \ No newline at end of file diff --git a/Docs/Docs/Samples.md b/Docs/Docs/Samples.md deleted file mode 100644 index e69de29b..00000000 diff --git a/README.md b/README.md index 96bed3b6..ed41bdc4 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ ## Quick Links * [Getting Started](./Docs/GettingStarted.md) +* [Command Line Interface (CLI)](./Docs/CLI.md) * [Samples](./Docs/Samples.md) +* [Architecture](./Docs/Architecture.md) ## Overview Soup is a build system that was created to simplify many aspects of developing C++. Soup was built from the ground up with C++20 Modules as a core principle for inter-project references. By only sharing a single module interface between the individual packages we can ensure that the internals of one project will not "leak" into other downstream dependencies. Soup also uses "just in time" compiled binaries to implement build extensions. These two aspects together allows for easy authoring of a project with custom build steps that can be shared with other teams or organizations (Package Manager!) and will allow for the ability to introduce breaking syntax changes in future versions of C++ while maintaining interface level compatibility (Epochs!).