teapot 3.6.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a21ff20aa745863cf4e91ffa997690d86c4de3a3f0fd3355f63b74ff432000ea
-  data.tar.gz: 53011f5117cc8c25437dbf2a5ea762298107761f58cc35c9df8d2030f5dc7777
+  metadata.gz: 742147841aebb1df987a75d2ffefcb764d9d42f6faf5492bdd273c62a8e195ce
+  data.tar.gz: 11c7a76cfe57be54d9a5864b2e0d7eb821ab780c4128df78ca09e555599c7dca
 SHA512:
-  metadata.gz: d3bb453fc48543c8ad03c681c2945c421cd4e9828ff5658961d3308e4eae6a354e0ba678fd394d7554e2f6dbdc6a70f32e02ca6b58210c8b1fcaaeb3f4658c2d
-  data.tar.gz: 0c7b89c76b6f1e045071a9137d3b387003ed9b4bf6e659b80f64a417f1e7558fe2851fa7f47b0bbc05ae13868ae77389d10f281c7ba0595ee640f2edfedf0374
+  metadata.gz: '001587e6eca1be37e6697b2b603208afe8d5685b14a8364603325d9aa24af9c2af3a12effec6bf0f9513731cffd05d7ec76125333d3fa3fd9a76e9cf66467749'
+  data.tar.gz: 503bd6ed1aba820ce830b5e856468b9d990b179e2f2da32c7d1985a314f1e6ff48a54d8a0883a1352b7dd30380e51c951e2fdbf234d716926033700208f88b3a

data/context/getting-started.md

@@ -0,0 +1,139 @@
+# Getting Started
+
+This guide explains how to use `teapot` to manage cross-platform project dependencies and build systems.
+
+## Installation
+
+Ensure that you already have a working install of Ruby 2.0.0+ and run the following to install `teapot`:
+
+~~~ bash
+$ gem install teapot
+~~~
+
+## Create Project
+
+Firstly, create your project by running:
+
+~~~ bash
+$ 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:
+
+~~~ bash
+$ teapot list
+... lots of output ...
+~~~
+
+To only see things exported by your current project, you can run:
+
+~~~ bash
+$ 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.
+
+~~~ bash
+$ teapot Test/MyProject
+~~~
+
+### Wildcard Targets
+
+To run all tests:
+
+~~~ bash
+$ teapot "Test/*"
+~~~
+
+Provided you are using an environment that supports sanitizers, you can test more thoroughly using:
+
+~~~ bash
+$ teapot "Test/*" variant-sanitize
+~~~
+
+## Run Project
+
+We can now build and run the project executable:
+
+~~~ bash
+$ 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:
+
+~~~ bash
+$ cd teapot/platforms/development/$PLATFORM-debug/bin
+$ ./$PROJECT_NAME
+~~~
+
+## Cloning Project
+
+You can clone another project which will fetch all dependencies:
+
+~~~ bash
+$ teapot clone https://github.com/kurocha/tagged-format
+$ cd tagged-format
+$ teapot build Executable/TaggedFormat
+~~~

data/context/index.yaml

@@ -0,0 +1,13 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Teapot is a tool for managing cross-platform builds.
+metadata:
+  documentation_uri: https://ioquatix.github.io/teapot/
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/ioquatix/teapot
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `teapot` to manage cross-platform project
+    dependencies and build systems.

data/lib/teapot/command/build.rb

@@ -9,9 +9,11 @@ require "build/controller"
 
 module Teapot
 	module Command
+		# Raised when the build fails.
 		class BuildFailedError < StandardError
 		end
 		
+		# A command to build targets in the project.
 		class Build < Selection
 			self.description = "Build the specified target."
 			
@@ -23,6 +25,8 @@ module Teapot
 			many :targets, "Build these targets, or use them to help the dependency resolution process."
 			split :argv, "Arguments passed to child process(es) of build if any."
 			
+			# Build the selected targets or default build targets, resolving dependencies and executing the build controller.
+			# @returns [Build::Dependency::Chain] The dependency chain.
 			def call
 				context = parent.context
 				
@@ -65,6 +69,8 @@ module Teapot
 				return chain
 			end
 			
+			# Display task dependencies for debugging, showing which tasks generate which outputs.
+			# @parameter walker [Build::Walker] The build walker.
 			def show_dependencies(walker)
 				outputs = {}
 				

data/lib/teapot/command/clean.rb

@@ -7,9 +7,11 @@ require "samovar"
 
 module Teapot
 	module Command
+		# A command to clean build artifacts.
 		class Clean < Samovar::Command
 			self.description = "Delete everything in the teapot directory."
 			
+			# Delete build output directories for the specified targets or all targets.
 			def call
 				context = parent.context
 				logger = parent.logger

data/lib/teapot/command/clone.rb

@@ -13,11 +13,13 @@ require "build/uri"
 
 module Teapot
 	module Command
+		# A command to clone a remote repository and fetch all dependencies.
 		class Clone < Samovar::Command
 			self.description = "Clone a remote repository and fetch all dependencies."
 			
 			one :source, "The source repository to clone.", required: true
 			
+			# Clone packages from their remote repositories using git, parallelizing the operations.
 			def call
 				logger = parent.logger
 				
@@ -37,6 +39,11 @@ module Teapot
 				Fetch[parent: nested].call
 			end
 			
+			# Provide credentials for repository authentication.
+			# @parameter url [String] The repository URL.
+			# @parameter username [String] The username.
+			# @parameter types [Array] The credential types allowed.
+			# @returns [Rugged::Credentials] The credentials object.
 			def credentials(url, username, types)
 				# We should prompt for username/password if required...
 				return Rugged::Credentials::SshKeyFromAgent.new(username: username)

data/lib/teapot/command/create.rb

@@ -11,6 +11,7 @@ require "rugged"
 
 module Teapot
 	module Command
+		# A command to create a new teapot project.
 		class Create < Samovar::Command
 			self.description = "Create a new teapot package using the specified repository."
 			
@@ -18,6 +19,7 @@ module Teapot
 			one :source, "The source repository to use for fetching packages, e.g. https://github.com/kurocha.", required: true
 			many :packages, "Any packages you'd like to include in the project.", default: ["generate-project"]
 			
+			# Create a new project directory structure with default teapot.rb configuration.
 			def call
 				logger = parent.logger
 				
@@ -64,6 +66,11 @@ module Teapot
 				)
 			end
 			
+			# Generate the initial project files.
+			# @parameter root [Build::Files::Path] The project root path.
+			# @parameter name [String] The project name.
+			# @parameter source [String] The source repository URL.
+			# @parameter packages [Array(String)] The packages to include.
 			def generate_project(root, name, source, packages)
 				name = ::Build::Name.new(name)
 				

data/lib/teapot/command/fetch.rb

@@ -8,7 +8,10 @@ require "rugged"
 
 module Teapot
 	module Command
+		# Raised when a fetch operation fails.
 		class FetchError < StandardError
+			# @parameter package [Package] The package that caused the error.
+			# @parameter message [String] The error message.
 			def initialize(package, message)
 				super(message)
 				@package = package
@@ -17,6 +20,7 @@ module Teapot
 			attr :package
 		end
 		
+		# A command to fetch remote packages and dependencies.
 		class Fetch < Samovar::Command
 			self.description = "Fetch remote packages according to the specified configuration."
 			
@@ -32,10 +36,13 @@ module Teapot
 			
 			many :packages, "Only update the specified packages, or all packages if none specified."
 			
+			# Get the context for this command.
+			# @returns [Context] The current context.
 			def context
 				parent.context
 			end
 			
+			# Update packages by pulling latest changes from their git remotes, subject to lock file constraints.
 			def call
 				selection = context.select
 				

data/lib/teapot/command/list.rb

@@ -10,9 +10,13 @@ require_relative "selection"
 
 module Teapot
 	module Command
+		# A command to list project definitions and dependencies.
 		class List < Selection
 			self.description = "List provisions and dependencies of the specified package."
 			
+			# Create a terminal with custom styles for colorizing different definition types in output.
+			# @parameter output [IO] The output stream.
+			# @returns [Console::Terminal] The configured terminal.
 			def terminal(output = $stdout)
 				Console::Terminal.for(output).tap do |terminal|
 					terminal[:definition] = terminal.style(nil, nil, :bright)
@@ -24,6 +28,8 @@ module Teapot
 				end
 			end
 			
+			# Process and display the selection.
+			# @parameter selection [Select] The selection to process.
 			def process(selection)
 				context = selection.context
 				terminal = self.terminal

data/lib/teapot/command/selection.rb

@@ -7,17 +7,23 @@ require "samovar"
 
 module Teapot
 	module Command
+		# Base class for commands that work with selections.
 		class Selection < Samovar::Command
 			options
 			
 			many :targets, "Only consider the specified targets, if any."
 			
+			# The set of target names to process, or nil if no targets were specified.
+			# @returns [Set | Nil] The set of target names.
 			def targets
 				if @targets and @targets.any?
 					Set.new(@targets)
 				end
 			end
 			
+			# Get the selection for the given context.
+			# @parameter context [Context] The project context.
+			# @returns [Select] The selection.
 			def selection(context)
 				if targets = self.targets
 					context.select(targets)
@@ -26,6 +32,7 @@ module Teapot
 				end
 			end
 			
+			# Execute the selection command.
 			def call
 				context = parent.context
 				

data/lib/teapot/command/status.rb

@@ -9,9 +9,13 @@ require "console/terminal"
 
 module Teapot
 	module Command
+		# A command to show git status of packages.
 		class Status < Selection
 			self.description = "List the git status of the specified package(s)."
 			
+			# Create a terminal with custom styles for colorizing git status information.
+			# @parameter output [IO] The output stream.
+			# @returns [Console::Terminal] The configured terminal.
 			def terminal(output = $stdout)
 				Console::Terminal.for(output).tap do |terminal|
 					terminal[:worktree_new] = terminal.style(:green)
@@ -20,6 +24,9 @@ module Teapot
 				end
 			end
 			
+			# Open the git repository for a package, or return nil if the package doesn't have a repository yet.
+			# @parameter package [Package] The package.
+			# @returns [Rugged::Repository | Nil] The repository or nil.
 			def repository_for(package)
 				Rugged::Repository.new(package.path.to_s)
 			rescue Rugged::RepositoryError
@@ -27,6 +34,8 @@ module Teapot
 				nil
 			end
 			
+			# Process and display the selection.
+			# @parameter selection [Select] The selection to process.
 			def process(selection)
 				context = selection.context
 				terminal = self.terminal

data/lib/teapot/command/visualize.rb

@@ -8,6 +8,7 @@ require "graphviz"
 
 module Teapot
 	module Command
+		# A command to visualize the dependency graph.
 		class Visualize < Selection
 			self.description = "Generate a picture of the dependency graph."
 			
@@ -16,14 +17,21 @@ module Teapot
 				option "-d/--dependency-name <name>", "Show the partial chain for the given named dependency."
 			end
 			
+			# Get the dependency names to visualize.
+			# @returns [Array(String)] The dependency names.
 			def dependency_names
 				@targets || []
 			end
 			
+			# Get the specific dependency name to visualize.
+			# @returns [String | Nil] The dependency name.
 			def dependency_name
 				@options[:dependency_name]
 			end
 			
+			# Process and generate the visualization.
+			# @parameter selection [Select] The selection to visualize.
+			# @returns [Graphviz::Graph] The generated graph.
 			def process(selection)
 				context = selection.context
 				chain = selection.chain

data/lib/teapot/command.rb

@@ -23,7 +23,9 @@ require "fileutils"
 require "console"
 
 module Teapot
+	# @namespace
 	module Command
+		# Represents the top-level command for the teapot CLI.
 		class Top < Samovar::Command
 			self.description = "A decentralised package manager and build tool."
 			
@@ -46,18 +48,26 @@ module Teapot
 				"clean" => Clean,
 			}, default: "build"
 			
+			# The project root directory, either from --root option or current working directory.
+			# @returns [Build::Files::Path] The root directory path.
 			def root
 				::Build::Files::Path.expand(@options[:root] || Dir.getwd)
 			end
 			
+			# Whether verbose logging is enabled via --verbose flag.
+			# @returns [Boolean] True if verbose mode is enabled.
 			def verbose?
 				@options[:logging] == :verbose
 			end
 			
+			# Whether quiet logging is enabled via --quiet flag.
+			# @returns [Boolean] True if quiet mode is enabled.
 			def quiet?
 				@options[:logging] == :quiet
 			end
 			
+			# Get the logger for the command.
+			# @returns [Console::Logger] The configured logger instance.
 			def logger
 				@logger ||= Console::Logger.new(Console.logger, verbose: self.verbose?).tap do |logger|
 					if verbose?
@@ -70,14 +80,20 @@ module Teapot
 				end
 			end
 			
+			# The build configuration name from -c option or TEAPOT_CONFIGURATION environment variable.
+			# @returns [String | Nil] The configuration name if specified.
 			def configuration
 				@options[:configuration]
 			end
 			
+			# Create a context for the project.
+			# @parameter root [Build::Files::Path] The root directory path.
+			# @returns [Context] A new context instance.
 			def context(root = self.root)
 				Context.new(root, configuration: configuration)
 			end
 			
+			# Execute the command.
 			def call
 				if @options[:version]
 					puts "teapot v#{Teapot::VERSION}"

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.6.1"
 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,13 @@ 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.6.0
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teapot
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.6.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -150,20 +150,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: graphviz
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: process-group
   requirement: !ruby/object:Gem::Requirement
@@ -226,6 +212,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bin/teapot
+- context/getting-started.md
+- context/index.yaml
 - lib/teapot.rb
 - lib/teapot/command.rb
 - lib/teapot/command/build.rb
@@ -250,10 +238,12 @@ files:
 - notes.md
 - readme.md
 - releases.md
-homepage: http://www.teapot.nz
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://ioquatix.github.io/teapot/
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/ioquatix/teapot
 rdoc_options: []
 require_paths:
 - lib
@@ -270,5 +260,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Teapot is a tool for managing complex cross-platform builds.
+summary: Teapot is a tool for managing cross-platform builds.
 test_files: []