Skip to content

Commit

Permalink
Lowercase docs (#289)
Browse files Browse the repository at this point in the history
* Update paths
* Rename docs
  • Loading branch information
mwasplund authored Jan 2, 2025
1 parent fe17acd commit 4ee48eb
Show file tree
Hide file tree
Showing 57 changed files with 101 additions and 101 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The entire system is programming language agnostic and allows for easy integrati
* [Simple Minimal Language (SML)](./Docs/SML.md) - The documentation for the Declarative language used by Soup Recipes.

## Release Status
Soup is currently in an `Beta` stage. This means that anyone is welcome to play around with the source code or the releases on GitHub, however there may be breaking changes in the internal structures and definitions as work is completed. It is therefor recommended not to be used in any production capacity. The design is stabilizing over time and [Version 1](https://github.com/SoupBuild/Soup/milestone/2) will be released when we believe there will be no more breaking changes or security concerns that would block a first release.
Soup is currently in an `Beta` stage. This means that anyone is welcome to play around with the source code or the releases on GitHub, however there may be breaking changes in the internal structures and definitions as work is completed. It is therefor recommended not to be used in any production capacity. The design is stabilizing over time and [Version 1](https://github.com/soup-build/soup/milestone/2) will be released when we believe there will be no more breaking changes or security concerns that would block a first release.

## Contributing
Soup is currently in active prototyping and testing. If you are interested in contributing to the project feel free to submit a PR or download the latest release and file an issue with suggestions or bugs. :smile:.
Expand Down
2 changes: 1 addition & 1 deletion code/generate-sharp/package-manager/WebPageBuilder.cs
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ public static class WebPageBuilder
<div class="container">
&copy; 2020-2024 - Soup Build
<ul class="nav">
<li class="nav-item"><a class="nav-link ps-0" href="https://github.com/SoupBuild/Soup" target="_blank" rel="noopener noreferrer">GitHub</a></li>
<li class="nav-item"><a class="nav-link ps-0" href="https://github.com/soup-build/soup" target="_blank" rel="noopener noreferrer">GitHub</a></li>
</ul>
</div>
</footer>
Expand Down
24 changes: 0 additions & 24 deletions docs/CLI.md

This file was deleted.

16 changes: 8 additions & 8 deletions docs/Architecture.md → docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,26 @@
The **Soup** build system utilizes a three phased approach to building code. A **declarative** frontend that tells the build **what** to build. A **generate** layer then defines **how** to build the requested definition. And finally, the **evaluate** engine **runs** the build.

## Declaration
There are four ways to declare the state for an invocation of a build. Through the command line application, from the Recipe file for each package, from a Root Recipe file that is shared with packages in the same folder hierarchy and from the global user config. All input state is combined into a single [Active State Table](Architecture/Active-State-Table.md) which is consumed by the Generate Phase.
There are four ways to declare the state for an invocation of a build. Through the command line application, from the Recipe file for each package, from a Root Recipe file that is shared with packages in the same folder hierarchy and from the global user config. All input state is combined into a single [Active State Table](architecture/active-state-table.md) which is consumed by the Generate Phase.

### Application
The [Command Line Interface (CLI)](CLI.md) is the first thing a user will see when they interact with the Soup build system. The CLI is primarily there to take user input through a set of parameters and flags to pass temporary configuration values into the build execution. The command parameters will be used to generate a unique output folder for the given build to allow for individual builds to coexist for the same package (i.e. Release vs Debug). The argument properties will be combined with a set of generated properties from the application that are passed into the next phase of the build through a [Parameters Table](Architecture/Parameters-Table.md).
The [Command Line Interface (CLI)](cli.md) is the first thing a user will see when they interact with the Soup build system. The CLI is primarily there to take user input through a set of parameters and flags to pass temporary configuration values into the build execution. The command parameters will be used to generate a unique output folder for the given build to allow for individual builds to coexist for the same package (i.e. Release vs Debug). The argument properties will be combined with a set of generated properties from the application that are passed into the next phase of the build through a [Parameters Table](architecture/parameters-table.md).

### Recipe
The build definition will use a declarative **Recipe** configuration file is how the user will configure their project. The Recipe file will utilize the [Simple Markup Language (SML)](./SML.md) language as a clean, human readable, definition that supports a core set of data types. The file can be thought of as a simple property bag for setting shared parameters into the build system for an individual package.
The build definition will use a declarative **Recipe** configuration file is how the user will configure their project. The Recipe file will utilize the [Simple Markup Language (SML)](./sml.md) language as a clean, human readable, definition that supports a core set of data types. The file can be thought of as a simple property bag for setting shared parameters into the build system for an individual package.

There are a few "known" property values that will be used within the build engine itself; however, the entire contents will be provided as initial input to the build engine.

### Root Recipe
When processing the state for a given Recipe file the system will walk up the directory structure for the first instance of a [Root Recipe](Architecture/Root-Recipe.md). This file is used as a shared set of properties that can be used by multiple packages.
When processing the state for a given Recipe file the system will walk up the directory structure for the first instance of a [Root Recipe](architecture/root-recipe.md). This file is used as a shared set of properties that can be used by multiple packages.

### Local User Config
The [Local User Config](Architecture/Local-User-Config.md) allows the user to specify external SDK definitions that will grant read access to the specified folders and pass in the shared state to the build.
The [Local User Config](architecture/local-user-config.md) allows the user to specify external SDK definitions that will grant read access to the specified folders and pass in the shared state to the build.

## Generate
The Generate Phase takes the combined input Declaration along with the [Shared State](Architecture/Shared-State-Table.md) Generated from the dependencies and generates the [Operation](Architecture/assets/Build-Operation.md) Graph that will be passed to the Evaluate phase, along with the output Shared State that downstream dependencies will consume.
The Generate Phase takes the combined input Declaration along with the [Shared State](architecture/shared-state-table.md) Generated from the dependencies and generates the [Operation](architecture/build-operation.md) Graph that will be passed to the Evaluate phase, along with the output Shared State that downstream dependencies will consume.

All build logic is injected into the Generate phase through the [Build Extension](Architecture/Build-Extension.md) framework. Each build extension is simply a C# library package that contains one or more public implementations of the `SoupTask` interface. When referenced from another Recipe as a **Build** dependency the Generate Engine will discover and instantiate all instances of the build tasks. Each build task contains of a set of run before and after lists that instruct the Generate Engine in what order to run the tasks to ensure shared state is setup in the correct order. The tasks then invoke their single Run method that will allow them to read and write from the active and shared state and generate build Operations.
All build logic is injected into the Generate phase through the [Build Extension](architecture/build-extension.md) framework. Each build extension is simply a C# library package that contains one or more public implementations of the `SoupTask` interface. When referenced from another Recipe as a **Build** dependency the Generate Engine will discover and instantiate all instances of the build tasks. Each build task contains of a set of run before and after lists that instruct the Generate Engine in what order to run the tasks to ensure shared state is setup in the correct order. The tasks then invoke their single Run method that will allow them to read and write from the active and shared state and generate build Operations.

Along with the list of explicit Build dependencies that inject build extensions, the **Language** property also instructs Soup to add the default tasks for that language.

Expand Down Expand Up @@ -63,7 +63,7 @@ This work can be broken down into five phases:
* Monitor the actual file system access (using Detours on Windows, open question for other platforms) to verify the declared input/output files match reality.

## Package Manager
You may have noticed that nothing about the build explicitly deals with the integration of a public feed of packages. Because each individual projects build is isolated and self contained, a dependency [Package Reference](Architecture/Package-Reference.md) can easily be migrated from a directory reference, for local projects, to a name@version pair that will be resolved to a published snapshot of a public project. The CLI application will consume a rest API from a hosted web service that allows for users to install other projects and publish the code they would like to share with ease. The build Engine will then have a small amount of integration logic that knows where to look when resolving dependencies that reference a public package that will be installed to a known location. It should be noted that these public dependency references can be for both runtime and developer dependencies. This will allow for shared packages to contain custom build logic and for the creation of shared build Extensions to augment the built in build Tasks.
You may have noticed that nothing about the build explicitly deals with the integration of a public feed of packages. Because each individual projects build is isolated and self contained, a dependency [Package Reference](architecture/package-reference.md) can easily be migrated from a directory reference, for local projects, to a name@version pair that will be resolved to a published snapshot of a public project. The CLI application will consume a rest API from a hosted web service that allows for users to install other projects and publish the code they would like to share with ease. The build Engine will then have a small amount of integration logic that knows where to look when resolving dependencies that reference a public package that will be installed to a known location. It should be noted that these public dependency references can be for both runtime and developer dependencies. This will allow for shared packages to contain custom build logic and for the creation of shared build Extensions to augment the built in build Tasks.

## Open Questions
* Find replacement for Windows Detours on Linux and macOS.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ The root table that provides input and output state from individual build tasks
## Known Keys

### "Parameters"
The [Parameters Table](Parameters-Table.md) that contains the input from the Command Line Application.
The [Parameters Table](parameters-table.md) that contains the input from the Command Line Application.

### "Recipe"
The duplicated state of the [Recipe](Recipe.md) file.
The duplicated state of the [Recipe](recipe.md) file.

### "Dependencies"
The table which a key for each direct dependency referenced from the Recipe file. The value contains the [Shared State Table](Shared-State-Table.md) from the resulting outputs from the generate phase of the referenced package build.
The table which a key for each direct dependency referenced from the Recipe file. The value contains the [Shared State Table](shared-state-table.md) from the resulting outputs from the generate phase of the referenced package build.

Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Build Extension

A [Wren](https://wren.io/) package that contains one or more implementations of the [Build Task](Build-Task.md) interface. When referenced as a **Build** Dependency within a [Recipe](Recipe.md) the Generate runtime will automatically discover and instantiate one instance of each public class that implements the shared interface definition. The
A [Wren](https://wren.io/) package that contains one or more implementations of the [Build Task](build-task.md) interface. When referenced as a **Build** Dependency within a [Recipe](recipe.md) the Generate runtime will automatically discover and instantiate one instance of each public class that implements the shared interface definition. The
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Local User Config

The Local User config allows for a set of properties to be set for an individual user. Currently the only state that is used from this file is the list of SDKs. The [SWhere](../Tools/SWhere.md) can be used to automatically fill in this file with the VSWhere tooling.
The Local User config allows for a set of properties to be set for an individual user. Currently the only state that is used from this file is the list of SDKs. The [SWhere](../tools/swhere.md) can be used to automatically fill in this file with the VSWhere tooling.

## "SDK"
A special table that allows for registering external SDKs. These allow for passing in Properties and a list of directories that should be allowed read access.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ A **Package Reference** is a special format string that can either be a director
> Note2: While absolute paths are allowed, they are strongly discouraged as they do not lend themselves to sharing code with others.
```
"../../OtherPackage/"
"../../other-package/"
```

```
Expand Down
File renamed without changes.
8 changes: 4 additions & 4 deletions docs/architecture/Recipe.md → docs/architecture/recipe.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Recipe

The Recipe file is the definition for a code package and will always be located at the root of the package directory structure. It is written in the [Simple Markup Language (SML)](../SML.md) declarative language.
The Recipe file is the definition for a code package and will always be located at the root of the package directory structure. It is written in the [Simple Markup Language (SML)](../sml.md) declarative language.

> Note: Adopted as a simplification of the TOML design.
Expand All @@ -13,7 +13,7 @@ Name: "MyAwesomePackage"
```

### Language
The **Language** property is required for all packages. It consists of a string value that contains the language type and minimum build version. This language tells Soup what default [Build Tasks](Build-Task.md) to inject into the build.
The **Language** property is required for all packages. It consists of a string value that contains the language type and minimum build version. This language tells Soup what default [Build Tasks](build-task.md) to inject into the build.
```
Language: (C#@0)
```
Expand All @@ -25,7 +25,7 @@ Version: 1.0.0
```

### Dependencies
The **Dependencies** property is a table of different dependency types that each consist of a list of dependency values. A dependency value can either be a string value with a [Package Reference](Package-Reference.md) or a table with a required **Reference** property that contains the Package Reference. The runtime will recursively build the dependencies and inject shared properties and allow read access for builds.
The **Dependencies** property is a table of different dependency types that each consist of a list of dependency values. A dependency value can either be a string value with a [Package Reference](package-reference.md) or a table with a required **Reference** property that contains the Package Reference. The runtime will recursively build the dependencies and inject shared properties and allow read access for builds.
```
Dependencies: {
Runtime: [
Expand All @@ -37,4 +37,4 @@ Dependencies: {
```

#### Build Dependencies
Build dependencies are a special set that are assumed to be C# Dynamic Libraries containing [Build Tasks](Build-Task.md). These build tasks will be loaded into the build generate and allow for shared build logic.
Build dependencies are a special set that are assumed to be C# Dynamic Libraries containing [Build Tasks](build-task.md). These build tasks will be loaded into the build generate and allow for shared build logic.
File renamed without changes.
File renamed without changes.
File renamed without changes.
24 changes: 24 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# 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 <command> [arguments]
```

* [Build](cli/build.md) - Perform a build with a specified root Package.

* [Init](cli/init.md) - Initialize a new Package with default properties.

* [Install](cli/install.md) - Install a new dependency for a specified Package.

* [Publish](cli/publish.md) - Publish a given package to the public feed.

* [Restore](cli/restore.md) - Restore all external package references in the target project closure.

* [Run](cli/run.md) - Invoke the executable result (if applicable) for a specified package.

* [Target](cli/target.md) - Prints the target directory for a specified package.

* [Version](cli/version.md) - Print the version of the current installed Soup application.

* [View](cli/view.md) - Launch the Soup View tool.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/cli/View.md → docs/cli/view.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# View
## Overview
Launch the Soup View untility GUI for visualizing the build dependency, tasks and operation graphs.
Launch the Soup View utility GUI for visualizing the build dependency, tasks and operation graphs.
```
soup view <path>
```

`path` - 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 command will use the current active directory.

## Examples
Luanch the tool in the current directory for debug with default configurations.
Launch the tool in the current directory for debug with default configurations.
```
soup view
```
File renamed without changes.
File renamed without changes.
16 changes: 8 additions & 8 deletions docs/Create-Release.md → docs/create-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,18 @@ Create a PR with this change.

## Build Windows Release
```
./Scripts/Windows/build.cmd Release
./Scripts/Windows/soup-release.cmd version
./Scripts/Windows/SignRuntime.cmd
./Scripts/Windows/release.cmd
./Scripts/Windows/SignInstaller.cmd
./scripts/windows/build.cmd Release
./scripts/windows/soup-release.cmd version
./scripts/windows/SignRuntime.cmd
./scripts/windows/release.cmd
./scripts/windows/SignInstaller.cmd
```

## Build Linux Release
```
./Scripts/Linux/build
./Scripts/Linux/soup version
./Scripts/Linux/release
./scripts/linux/build
./scripts/linux/soup version
./scripts/linux/release
```

## Create a GitHub Release
Expand Down
File renamed without changes.
File renamed without changes.
Loading

0 comments on commit 4ee48eb

Please sign in to comment.