document :use better

doc/user_guide.md

@@ -323,6 +323,12 @@ defined, and defaults to `false` if the `:set_define` option is defined.
 If set, a build define of the specified String will be added to the
 `CPPDEFINES` construction variable array if the requested library is found.
 
+##### `:use`
+
+If not set, the library will be used by default in all `Environment` objects.
+If set, the library will only be used in `Environment` objects that have a
+matching `:use` flag set.
+
 ###> Checking for a Program
 
 The `check_program` method can check for the existence of an executable in the
@@ -377,6 +383,12 @@ defined, and defaults to `false` if the `:set_define` option is defined.
 If set, a build define of the specified String will be added to the
 `CPPDEFINES` construction variable array if the requested package is found.
 
+##### `:use`
+
+If not set, the library will be used by default in all `Environment` objects.
+If set, the library will only be used in `Environment` objects that have a
+matching `:use` flag set.
+
 ###> Custom Configuration Checks
 
 The `Rsconscript` author can add custom configuration checks to be performed

lib/rscons/basic_environment.rb

@@ -4,10 +4,11 @@ module Rscons
 
     # Create a BasicEnvironment object.
     #
-    # @api private
-    #
     # @param options [Hash]
     #   Construction options.
+    # @option options [String, Array<String>] :use
+    #   Use flag(s). If specified, any configuration flags which were saved
+    #   with a corresponding `:use` value will be applied to this Environment.
     def initialize(options = {})
       @varset = VarSet.new(Rscons::DEFAULT_CONSTRUCTION_VARIABLES)
       load_configuration_data!(options)

lib/rscons/configure_op.rb

@@ -301,6 +301,10 @@ module Rscons
     #   Hash containing the variables to merge.
     # @param options [Hash]
     #   Options.
+    # @option options [String] :use
+    #   A 'use' name. If specified, the construction variables are only applied
+    #   to an Environment if the Environment is constructed with a matching
+    #   `:use` value.
     def store_merge(vars, options = {})
       store_vars = store_common(options)
       store_vars["merge"] ||= {}
@@ -315,6 +319,10 @@ module Rscons
     #   Hash containing the variables to append.
     # @param options [Hash]
     #   Options.
+    # @option options [String] :use
+    #   A 'use' name. If specified, the construction variables are only applied
+    #   to an Environment if the Environment is constructed with a matching
+    #   `:use` value.
     def store_append(vars, options = {})
       store_vars = store_common(options)
       store_vars["append"] ||= {}
@@ -333,6 +341,10 @@ module Rscons
     #   String containing the flags to parse.
     # @param options [Hash]
     #   Options.
+    # @option options [String] :use
+    #   A 'use' name. If specified, the construction variables are only applied
+    #   to an Environment if the Environment is constructed with a matching
+    #   `:use` value.
     def store_parse(flags, options = {})
       store_vars = store_common(options)
       store_vars["parse"] ||= []

lib/rscons/environment.rb

@@ -59,6 +59,9 @@ module Rscons
     #   :command, :short, or :off (default :short)
     # @option options [Boolean] :exclude_builders
     #   Whether to omit adding default builders (default false)
+    # @option options [String, Array<String>] :use
+    #   Use flag(s). If specified, any configuration flags which were saved
+    #   with a corresponding `:use` value will be applied to this Environment.
     #
     # If a block is given, the Environment object is yielded to the block and
     # when the block returns, the {#process} method is automatically called.