Added more documentation for usages and uses

website/docs/Home.md

@@ -22,6 +22,7 @@ Welcome to the **Premake 5  User Guide**!
 * [Configurations and Platforms](Configurations-and-Platforms.md)
 * [Filters](Filters.md)
 * [Build Settings](Build-Settings.md)
+* [Usages and Uses](Usages-and-Uses.md)
 * [Command Line Arguments](Command-Line-Arguments.md)
 * [Using Modules](Using-Modules.md)
 * [More Topics…](Topics.md)

website/docs/Usages-and-Uses.md

@@ -0,0 +1,55 @@
+---
+title: Usages & Uses
+---
+
+Defining how libraries of code are to be used is a crucial piece of any build system. Premake exposes this functionality via the `usage` and `uses` APIs. A `usage` specifies a reusable configuration scope which can be later consumed by `uses`.
+
+Unlike other scopes, usages do not inherit their properties from their parent scopes. This is to ensure that consumers only receive the configuration explicitly specified by the usage block.
+
+```lua
+project "A"
+  defines { "A_PRIVATE_DEF" }
+  usage "PUBLIC"
+    defines { "A_PUBLIC_DEF" }
+
+project "B"
+    uses { "A" }
+    -- B will now contain the defines { "A_PUBLIC_DEF" }
+```
+
+Usage containers can be provided with any name, however Premake provides 3 names of power. `PUBLIC` specifies that a usage will be applied to the project defining the usage and any project consuming the usage. `INTERFACE` specifies that a usage will be applied to only projects consuming the usage. Finally, `PRIVATE` specifies that a usage will only be applied to the project defining the usage. The self application properties of `PRIVATE` and `PUBLIC` will happen without any need to specify `uses` for that project.  This is the same behavior as defining properties directly on the project.  Additionally, these names of power allow users to specify the project name containing the usage block, rather than having to fully type out the usage block name, in the `uses` statement.
+
+Usages are not applied recursively by default. This is to match the existing Premake behaviors where everything is private by default. In order to apply usages recursively, usage blocks can be utilized to specify which usages should be propagated to the children. This chain can be applied indefinitely by specifying the usages that should be applied in each project's `PUBLIC` block.
+
+```lua
+project "A"
+  usage "PUBLIC"
+    defines { "A_PUBLIC_DEF" }
+
+project "B"
+  usage "PUBLIC"
+    uses { "A" }
+    defines { "B_PUBLIC_DEF" }
+
+project "C"
+  -- C will now contain the defines { "A_PUBLIC_DEF", "B_PUBLIC_DEF" }
+  uses { "B" }
+```
+
+Similarly, for forcing consumers to link or depend on your project, we can specify a usage block as follows:
+
+```lua
+project "MyLib"
+  -- Force consumers to link MyLib, but do not force MyLib to link against it
+  usage "INTERFACE"
+    links { "MyLib" }
+
+project "MyExe"
+  -- MyExe will now link against MyLib
+  uses { "MyLib" }
+```
+
+### See Also ###
+
+* [usage](usage.md)
+* [uses](uses.md)

website/sidebars.js

@@ -24,6 +24,7 @@ module.exports = {
 				'Configurations-and-Platforms',
 				'Filters',
 				'Build-Settings',
+				'Usages-and-Uses',
 				'Command-Line-Arguments',
 				'Using-Modules',
 				'Topics'