teapot 3.6.0 → 3.7.0

data/lib/teapot/configuration.rb

@@ -20,6 +20,11 @@ module Teapot
 			:import => true
 		}.freeze
 		
+		# Initialize a new configuration.
+		# @parameter context [Context] The project context.
+		# @parameter package [Package] The package.
+		# @parameter name [String] The configuration name.
+		# @parameter packages [Array] The list of packages.
 		def initialize(context, package, name, packages = [], **options)
 			super context, package, name
 			
@@ -34,6 +39,7 @@ module Teapot
 			@targets = Hash.new{|hash,key| hash[key] = Array.new}
 		end
 		
+		# Make the configuration immutable to prevent modification after targets and packages are resolved.
 		def freeze
 			return self if frozen?
 			
@@ -48,6 +54,8 @@ module Teapot
 			super
 		end
 		
+		# Create an environment for this configuration.
+		# @returns [Build::Environment] The build environment.
 		def environment
 			configuration = self
 			
@@ -60,10 +68,13 @@ module Teapot
 		# Controls how the configuration is exposed in the context.
 		attr :visibility
 		
+		# Whether this configuration is publicly accessible (not hidden from listings).
+		# @returns [Boolean] True if public.
 		def public?
 			@visibility == :public
 		end
 		
+		# Mark this configuration as publicly visible in listings and help output.
 		def public!
 			@visibility = :public
 		end
@@ -112,7 +123,7 @@ module Teapot
 			@options[key] = value
 		end
 		
-		# Get a configuration option.
+		# Access configuration-specific settings that control build behavior and environment variables.
 		def [] key
 			@options[key]
 		end
@@ -129,14 +140,19 @@ module Teapot
 		
 		alias platforms_path build_path
 		
+		# Get the path to the lock file.
+		# @returns [Build::Files::Path] The lock file path.
 		def lock_path
 			context.root + "#{@name}-lock.yml"
 		end
 		
+		# Get the lock store for persisting state.
+		# @returns [YAML::Store] The lock store.
 		def lock_store
 			::YAML::Store.new(lock_path.to_s)
 		end
 		
+		# @returns [String] The string representation.
 		def to_s
 			"#<#{self.class} #{@name.dump} visibility=#{@visibility}>"
 		end

data/lib/teapot/context.rb

@@ -8,6 +8,8 @@ require_relative "select"
 module Teapot
 	# A context represents a specific root package instance with a given configuration and all related definitions. A context is stateful in the sense that package selection is specialized based on #select and #dependency_chain. These parameters are usually set up initially as part of the context setup.
 	class Context
+		# Initialize a new context.
+		# @parameter root [String] The root path.
 		def initialize(root, **options)
 			@root = Path[root]
 			@options = options
@@ -29,14 +31,22 @@ module Teapot
 		# The primary project.
 		attr :project
 		
+		# Discover and open the git repository for this context's root directory.
+		# @returns [Rugged::Repository] The git repository.
 		def repository
 			@repository ||= Rugged::Repository.discover(@root.to_s)
 		end
 		
+		# Create a selection that resolves dependencies and loads definitions for the specified targets or configurations.
+		# @parameter names [Array | Nil] The names to select.
+		# @parameter configuration [Configuration] The configuration to use.
+		# @returns [Select] The selection.
 		def select(names = nil, configuration = @configuration)
 			Select.new(self, configuration, names || [])
 		end
 		
+		# Get substitutions for template generation.
+		# @returns [Build::Text::Substitutions] The substitutions.
 		def substitutions
 			substitutions = Build::Text::Substitutions.new
 			
@@ -71,6 +81,9 @@ module Teapot
 			return substitutions
 		end
 		
+		# Load a package from its teapot.rb, tracking loaded packages to prevent duplicates.
+		# @parameter package [Package] The package to load.
+		# @returns [Script] The loaded script.
 		def load(package)
 			if loader = @loaded[package]
 				return loader.script unless loader.changed?

data/lib/teapot/definition.rb

@@ -4,7 +4,12 @@
 # Copyright, 2013-2026, by Samuel Williams.
 
 module Teapot
+	# Base class for definitions (target, configuration, or project).
 	class Definition
+		# Initialize a new definition.
+		# @parameter context [Context] The project context.
+		# @parameter package [Package] The package.
+		# @parameter name [String] The definition name.
 		def initialize(context, package, name)
 			@context = context
 			@package = package
@@ -14,6 +19,7 @@ module Teapot
 			@description = nil
 		end
 		
+		# Make the definition immutable after it has been loaded from a teapot file.
 		def freeze
 			@name.freeze
 			@description.freeze
@@ -21,6 +27,7 @@ module Teapot
 			super
 		end
 		
+		# @returns [String] The string representation.
 		def inspect
 			"\#<#{self.class.name} #{@name}>"
 		end
@@ -37,6 +44,8 @@ module Teapot
 		# A textual description of the definition, possibly in markdown format:
 		attr :description
 		
+		# Assign a description with automatic removal of common leading indentation.
+		# @parameter text [String] The description text.
 		def description=(text)
 			if text =~ /^(\t+)/
 				text = text.gsub(/#{$1}/, "")
@@ -50,6 +59,7 @@ module Teapot
 			@package.path
 		end
 		
+		# @returns [String] The string representation.
 		def to_s
 			"#<#{self.class} #{@name.dump}>"
 		end

data/lib/teapot/loader.rb

@@ -24,7 +24,10 @@ module Teapot
 	# The package relative path to the file to load:
 	TEAPOT_FILE = "teapot.rb".freeze
 	
+	# Raised when a teapot file requires an incompatible version.
 	class IncompatibleTeapotError < StandardError
+		# @parameter package [Package] The package.
+		# @parameter version [String] The version.
 		def initialize(package, version)
 			super "Unsupported teapot_version #{version} in #{package.path}!"
 		end
@@ -32,7 +35,9 @@ module Teapot
 		attr :version
 	end
 	
+	# Raised when a teapot file cannot be found.
 	class MissingTeapotError < StandardError
+		# @parameter path [String] The file path.
 		def initialize(path)
 			super "Could not read file at #{path}!"
 		end
@@ -45,6 +50,10 @@ module Teapot
 		Files = Build::Files
 		Rule = Build::Rule
 		
+		# Initialize a new script.
+		# @parameter context [Context] The project context.
+		# @parameter package [Package] The package.
+		# @parameter path [String] The teapot file path.
 		def initialize(context, package, path = TEAPOT_FILE)
 			@context = context
 			@package = package
@@ -70,6 +79,8 @@ module Teapot
 		attr :default_project
 		attr :default_configuration
 		
+		# Specify the minimum required teapot gem version for compatibility checks.
+		# @parameter version [String] The required version.
 		def teapot_version(version)
 			version = version[0..2]
 			
@@ -82,6 +93,8 @@ module Teapot
 		
 		alias required_version teapot_version
 		
+		# Define a new project.
+		# @parameter arguments [Array] The definition arguments.
 		def define_project(*arguments, **options)
 			project = Project.new(@context, @package, *arguments, **options)
 			
@@ -91,6 +104,8 @@ module Teapot
 			@defined << project
 		end
 		
+		# Define a new target.
+		# @parameter arguments [Array] The definition arguments.
 		def define_target(*arguments, **options)
 			target = Target.new(@context, @package, *arguments, **options)
 			
@@ -101,6 +116,8 @@ module Teapot
 			@defined << target
 		end
 		
+		# Define a new configuration.
+		# @parameter arguments [Array] The definition arguments.
 		def define_configuration(*arguments, **options)
 			configuration = Configuration.new(@context, @package, *arguments, **options)
 			
@@ -127,6 +144,10 @@ module Teapot
 	
 	# Loads the teapot.rb script and can reload it if it was changed.
 	class Loader
+		# Initialize a new loader.
+		# @parameter context [Context] The project context.
+		# @parameter package [Package] The package.
+		# @parameter path [String] The teapot file path.
 		def initialize(context, package, path = TEAPOT_FILE)
 			@context = context
 			@package = package
@@ -139,14 +160,20 @@ module Teapot
 		
 		attr :script
 		
+		# The absolute path to the teapot.rb file for this package.
+		# @returns [Build::Files::Path] The teapot file path.
 		def teapot_path
 			@package.path + @path
 		end
 		
+		# Whether the teapot file has been modified since it was loaded.
+		# @returns [Boolean] True if changed.
 		def changed?
 			File.mtime(teapot_path) > @mtime
 		end
 		
+		# Reload the loader with fresh data.
+		# @returns [Loader] A new loader instance.
 		def reload
 			self.class.new(@context, @package, @path)
 		end

data/lib/teapot/package.rb

@@ -11,7 +11,12 @@ require_relative "definition"
 module Teapot
 	Path = Build::Files::Path
 	
+	# A package in the dependency graph.
 	class Package
+		# Initialize a new package.
+		# @parameter path [String] The package path.
+		# @parameter name [String | Symbol] The package name or URI.
+		# @parameter options [Hash] Additional options.
 		def initialize(path, name, options = {})
 			# The path where the package is (or will be) located:
 			@path = Path[path]
@@ -35,6 +40,7 @@ module Teapot
 			@options = options
 		end
 		
+		# Make the package immutable to prevent modification after it's been loaded and processed.
 		def freeze
 			@path.freeze
 			@name.freeze
@@ -50,14 +56,20 @@ module Teapot
 		attr :uri
 		attr_accessor :options
 		
+		# The local filesystem path if this package is linked rather than cloned.
+		# @returns [String] The local path.
 		def local
 			@options[:local].to_s
 		end
 		
+		# Whether this package is linked from a local path instead of being cloned from a remote repository.
+		# @returns [Boolean] True if local.
 		def local?
 			@options.include?(:local)
 		end
 		
+		# Whether this package should be cloned from an external source repository.
+		# @returns [Boolean] True if external.
 		def external?
 			@options.include?(:source)
 		end
@@ -67,10 +79,14 @@ module Teapot
 			Build::URI[@options[:source]]
 		end
 		
+		# Construct the full URL from which this package should be cloned, combining the root path, source URI, and package URI.
+		# @parameter root_path [String | Nil] The root path.
+		# @returns [Build::URI] The external URL.
 		def external_url(root_path = nil)
 			Build::URI[root_path] + source_uri + Build::URI[@uri]
 		end
 		
+		# @returns [String] The string representation.
 		def to_s
 			if self.local?
 				"links #{@name} from #{self.local}"
@@ -83,10 +99,15 @@ module Teapot
 		
 		# Package may be used as hash key / in a set:
 		
+		# Packages are hashed by path for use as hash keys and set members.
+		# @returns [Integer] The hash code.
 		def hash
 			@path.hash
 		end
 		
+		# Packages are considered equal if they have the same path.
+		# @parameter other [Package] The other package.
+		# @returns [Boolean] True if equal.
 		def eql?(other)
 			@path.eql?(other.path)
 		end

data/lib/teapot/project.rb

@@ -6,9 +6,14 @@
 require_relative "definition"
 
 module Teapot
+	# A project definition.
 	class Project < Definition
 		Author = Struct.new(:name, :email, :website)
 		
+		# Initialize a new project.
+		# @parameter context [Context] The project context.
+		# @parameter package [Package] The package.
+		# @parameter name [String] The project name.
 		def initialize(context, package, name)
 			super context, package, name
 			
@@ -16,6 +21,8 @@ module Teapot
 			@authors = []
 		end
 		
+		# Get the project name as a Build::Name object.
+		# @returns [Build::Name] The project name.
 		def name
 			if @title
 				# Prefer title, it retains case.
@@ -26,6 +33,7 @@ module Teapot
 			end
 		end
 		
+		# Make the project immutable after all packages and configurations have been loaded.
 		def freeze
 			@title.freeze
 			@summary.freeze
@@ -46,6 +54,9 @@ module Teapot
 		
 		attr :authors
 		
+		# Add an author to the project.
+		# @parameter name [String] The author name.
+		# @parameter options [Hash] Author options (email, website).
 		def add_author(name, options = {})
 			@authors << Author.new(name, options[:email], options[:website])
 		end

data/lib/teapot/select.rb

@@ -11,11 +11,17 @@ require "build/text/substitutions"
 require "build/text/merge"
 
 module Teapot
+	# Raised when a definition is already defined.
 	class AlreadyDefinedError < StandardError
+		# @parameter definition [Definition] The definition.
+		# @parameter previous [Definition] The previous definition.
 		def initialize(definition, previous)
 			super "Definition #{definition.name} in #{definition.path} has already been defined in #{previous.path}!"
 		end
 		
+		# Check if a definition would cause a conflict.
+		# @parameter definition [Definition] The definition to check.
+		# @parameter definitions [Hash] The existing definitions.
 		def self.check(definition, definitions)
 			previous = definitions[definition.name]
 			
@@ -25,6 +31,10 @@ module Teapot
 	
 	# A selection is a specific view of the data exposed by the context at a specific point in time.
 	class Select
+		# Initialize a new selection.
+		# @parameter context [Context] The project context.
+		# @parameter configuration [Configuration] The configuration.
+		# @parameter names [Array] The names to select.
 		def initialize(context, configuration, names = [])
 			@context = context
 			@configuration = Configuration.new(context, configuration.package, configuration.name, [], **configuration.options)
@@ -61,10 +71,15 @@ module Teapot
 		attr :resolved
 		attr :unresolved
 		
+		# Get the dependency chain.
+		# @returns [Build::Dependency::Chain] The dependency chain.
 		def chain
 			@chain ||= Build::Dependency::Chain.expand(@dependencies, @targets.values, @selection)
 		end
 		
+		# Extract the targets that directly satisfy the requested dependencies.
+		# @parameter ordered [Array] The ordered targets.
+		# @returns [Array] The direct targets.
 		def direct_targets(ordered)
 			@dependencies.collect do |dependency|
 				ordered.find{|(package, _)| package.provides? dependency}

data/lib/teapot/target.rb

@@ -11,18 +11,22 @@ require "build/environment"
 require "build/rulebook"
 
 module Teapot
+	# Raised during build operations.
 	class BuildError < StandardError
 	end
 	
+	# A build target.
 	class Target < Definition
 		include Build::Dependency
 		
+		# Initialize a new target.
 		def initialize(*)
 			super
 			
 			@build = nil
 		end
 		
+		# Make the target immutable after it has been completely defined with dependencies and build rules.
 		def freeze
 			return self if frozen?
 			
@@ -31,6 +35,9 @@ module Teapot
 			super
 		end
 		
+		# Define the build block for this target.
+		# @parameter block [Proc | Nil] The build block.
+		# @returns [Proc | Nil] The build block.
 		def build(&block)
 			if block_given?
 				@build = block
@@ -39,6 +46,7 @@ module Teapot
 			return @build
 		end
 		
+		# Update environments with the build block.
 		def update_environments!
 			return unless @build
 			

data/lib/teapot/version.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2012-2026, by Samuel Williams.
 
+# @namespace
 module Teapot
-	VERSION = "3.6.0"
+	VERSION = "3.7.0"
 end

data/lib/teapot.rb

@@ -4,8 +4,4 @@
 # Copyright, 2012-2026, by Samuel Williams.
 
 require "teapot/version"
-
 require "teapot/context"
-
-module Teapot
-end

data/readme.md

@@ -17,127 +17,17 @@ Ensure that you already have a working install of Ruby 2.0.0+ and run the follow
 
 ## Usage
 
-Please see the [project documentation](http://www.teapot.nz) for more details.
-
-### Create Project
-
-Firstly, create your project by running:
-
-    $ teapot create "My Project" https://github.com/kurocha generate-project
-    $ cd my-project
-
-You will be asked to merge the project file. At present, merge tools are not very good and thus you may need to take a moment to review the changes. You want to keep most of the original file, but you would like to add the `define_target` blocks which are being added.
-
-In the resulting project directory that has been created, you can see the list of dependencies:
-
-    $ teapot list
-    ... lots of output ...
-
-To only see things exported by your current project, you can run:
-
-    $ teapot list root
-    Package root (from /private/tmp/my-project):
-    	#<Teapot::Project "my-project">
-    		My Project description.
-    		- Summary: A brief one line summary of the project.
-    		- License: MIT License
-    		- Version: 0.1.0
-    		- Author: Samuel Williams <samuel.williams@oriontransfer.co.nz>
-    	#<Teapot::Target "my-project-library">
-    		- depends on "Build/Files"
-    		- depends on "Build/Clang"
-    		- depends on :platform
-    		- depends on "Language/C++14" {:private=>true}
-    		- provides "Library/MyProject"
-    	#<Teapot::Target "my-project-test">
-    		- depends on "Library/UnitTest"
-    		- depends on "Library/MyProject"
-    		- provides "Test/MyProject"
-    	#<Teapot::Target "my-project-executable">
-    		- depends on "Build/Files"
-    		- depends on "Build/Clang"
-    		- depends on :platform
-    		- depends on "Language/C++14" {:private=>true}
-    		- depends on "Library/MyProject"
-    		- provides "Executable/MyProject"
-    	#<Teapot::Target "my-project-run">
-    		- depends on "Executable/MyProject"
-    		- provides "Run/MyProject"
-    	#<Teapot::Configuration "development" visibility=private>
-    		- references root from /private/tmp/my-project
-    		- clones platforms from https://github.com/kurocha/platforms
-    		- clones unit-test from https://github.com/kurocha/unit-test
-    		- clones generate-cpp-class from https://github.com/kurocha/generate-cpp-class
-    		- clones generate-project from https://github.com/kurocha/generate-project
-    		- clones variants from https://github.com/kurocha/variants
-    		- clones platform-darwin-osx from https://github.com/kurocha/platform-darwin-osx
-    		- clones platform-darwin-ios from https://github.com/kurocha/platform-darwin-ios
-    		- clones build-clang from https://github.com/kurocha/build-clang
-    		- clones build-darwin from https://github.com/kurocha/build-darwin
-    		- clones build-files from https://github.com/kurocha/build-files
-    		- clones streams from https://github.com/kurocha/streams
-    		- clones generate-template from https://github.com/kurocha/generate-template
-    	#<Teapot::Configuration "my-project" visibility=public>
-    		- references root from /private/tmp/my-project
-
-### Run Tests
-
-Testing is a good idea, and teapot supports test driven development.
-
-    $ teapot Test/MyProject
-
-#### Wildcard Targets
-
-To run all tests:
-
-    $ teapot "Test/*"
-
-Provided you are using an environment that supports sanitizers, you can test more thoroughly using:
-
-    $ teapot "Test/*" variant-sanitize
-
-### Run Project
-
-We can now build and run the project executable:
-
-    $ teapot Run/MyProject
-    I'm a little teapot,
-    Short and stout,
-    Here is my handle (one hand on hip),
-    Here is my spout (other arm out with elbow and wrist bent).
-    When I get all steamed up,
-    Hear me shout,
-    Tip me over and pour me out! (lean over toward spout)
-    
-                                  ~
-                       ___^___   __
-                   .- /       \./ /
-                  /  /          _/
-                  \__|         |
-                      \_______/
-
-The resulting executables and libraries will be framework dependent, but are typically located in:
-
-    $ cd teapot/platforms/development/$PLATFORM-debug/bin
-    $ ./$PROJECT_NAME
-
-### Cloning Project
-
-You can clone another project which will fetch all dependencies:
-
-    $ teapot clone https://github.com/kurocha/tagged-format
-    $ cd tagged-format
-    $ teapot build Executable/TaggedFormat
-
-## Open Issues
-
-  - Should packages be built into a shared prefix or should they be built into unique prefixes and joined together either via install or `-L` and `-I`?
-      - Relative include paths might fail to work correctly if headers are not installed into same directory.
-  - Should packages have some way to expose system requirements, e.g. installed compiler, libraries, etc. Perhaps some kind of `Package#valid?` which allows custom logic?
+Please see the [project documentation](https://ioquatix.github.io/teapot/) for more details.
+
+  - [Getting Started](https://ioquatix.github.io/teapot/guides/getting-started/index) - This guide explains how to use `teapot` to manage cross-platform project dependencies and build systems.
 
 ## Releases
 
-Please see the [project releases](http://www.teapot.nzreleases/index) for all releases.
+Please see the [project releases](https://ioquatix.github.io/teapot/releases/index) for all releases.
+
+### v3.7.0
+
+  - `teapot visualize` has two new sub-commands: `packages` and `targets`. The former visualizes the dependency graph of packages, while the latter visualizes the dependency graph of targets. Both sub-commands output Mermaid diagrams, which can be rendered using Mermaid Live Editor or other Mermaid-compatible tools.
 
 ### v3.6.0
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v3.7.0
+
+  - `teapot visualize` has two new sub-commands: `packages` and `targets`. The former visualizes the dependency graph of packages, while the latter visualizes the dependency graph of targets. Both sub-commands output Mermaid diagrams, which can be rendered using Mermaid Live Editor or other Mermaid-compatible tools.
+
 ## v3.6.0
 
   - Update dependencies.