teapot 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a21ff20aa745863cf4e91ffa997690d86c4de3a3f0fd3355f63b74ff432000ea
-  data.tar.gz: 53011f5117cc8c25437dbf2a5ea762298107761f58cc35c9df8d2030f5dc7777
+  metadata.gz: 6fb45edfbd49bfea6e78038ec74bd4473be5a2f716edd0391907acf66d5a740c
+  data.tar.gz: 61012b133dc05dbd9fd5e240964313f387592361e08394c2602c024606f65d48
 SHA512:
-  metadata.gz: d3bb453fc48543c8ad03c681c2945c421cd4e9828ff5658961d3308e4eae6a354e0ba678fd394d7554e2f6dbdc6a70f32e02ca6b58210c8b1fcaaeb3f4658c2d
-  data.tar.gz: 0c7b89c76b6f1e045071a9137d3b387003ed9b4bf6e659b80f64a417f1e7558fe2851fa7f47b0bbc05ae13868ae77389d10f281c7ba0595ee640f2edfedf0374
+  metadata.gz: d1dfddcdc2485c1911367892d4be722a74c2aa2a5f2cc0943ad9b914896ec648b1276d8582cf4225f2ff864c8f8c7a5a9f1fff134c10bb1407abaae7c8ee933c
+  data.tar.gz: 39c8e42658208e0499fd22b0951e75218725622bcf83690b3290f230f1e5e7c710a6f0db1776036bd2b51b4108fc3ee9eef9b1ac8e65566385ba1677449204dd

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,20 +9,25 @@ 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."
 			
 			options do
 				option "-j/-l/--limit <n>", "Limit the build to <n> concurrent processes.", type: Integer
 				option "-c/--continuous", "Run the build graph continually (experimental)."
+				option "--show-dependencies", "Show task dependencies for debugging."
 			end
 			
 			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
 				
@@ -36,8 +41,8 @@ module Teapot
 				chain = selection.chain
 				environment = context.configuration.environment
 				
-				controller = ::Build::Controller.new(limit: @options[:limit]) do |controller|
-					controller.add_chain(chain, self.argv, environment)
+				controller = ::Build::Controller.build(limit: @options[:limit]) do |builder|
+					builder.add_chain(chain, self.argv, environment)
 				end
 				
 				walker = nil
@@ -45,7 +50,7 @@ module Teapot
 				# We need to catch interrupt here, and exit with the correct exit code:
 				begin
 					controller.run do |walker|
-						# show_dependencies(walker)
+						show_dependencies(walker) if @options[:show_dependencies]
 						
 						# Only run once is asked:
 						unless @options[:continuous]
@@ -65,6 +70,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

@@ -3,48 +3,174 @@
 # Released under the MIT License.
 # Copyright, 2017-2026, by Samuel Williams.
 
+require "samovar"
 require_relative "selection"
-require "graphviz"
+require "build/controller"
 
 module Teapot
 	module Command
-		class Visualize < Selection
-			self.description = "Generate a picture of the dependency graph."
+		# A command to visualize dependency graphs.
+		class Visualize < Samovar::Command
+			self.description = "Generate visualizations of package and target dependencies."
 			
-			options do
-				option "-o/--output-path <path>", "The output path for the visualization.", default: "dependency.svg"
-				option "-d/--dependency-name <name>", "Show the partial chain for the given named dependency."
-			end
-			
-			def dependency_names
-				@targets || []
-			end
-			
-			def dependency_name
-				@options[:dependency_name]
+			# Visualize package-level dependencies.
+			class Packages < Selection
+				self.description = "Visualize package-level dependencies from configuration.require."
+				
+				options do
+					option "-o/--output-path <path>", "The output path for the visualization."
+					option "-d/--dependency-name <name>", "Show the partial chain for the given named dependency."
+				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 package dependency visualization.
+				# @parameter selection [Select] The selection to visualize.
+				# @returns [String] The generated Mermaid diagram.
+				def process(selection)
+					chain = selection.chain
+					
+					if dependency_name
+						provider = selection.dependencies[dependency_name]
+						chain = chain.partial(provider)
+					end
+					
+					visualization = ::Build::Dependency::Visualization.new
+					diagram = visualization.generate(chain)
+					
+					if output_path = @options[:output_path]
+						File.write(output_path, diagram)
+					else
+						$stdout.puts diagram
+					end
+					
+					return diagram
+				end
 			end
 			
-			def process(selection)
-				context = selection.context
-				chain = selection.chain
+			# Visualize target-level dependencies.
+			class Targets < Selection
+				self.description = "Visualize target-level dependencies from target.depends."
 				
-				if dependency_name
-					provider = selection.dependencies[dependency_name]
+				options do
+					option "-o/--output-path <path>", "The output path for the visualization."
+				end
+				
+				# Process and generate the target dependency visualization.
+				# @parameter selection [Select] The selection to visualize.
+				# @returns [String] The generated Mermaid diagram.
+				def process(selection)
+					lines = ["flowchart LR"]
+					lines << ""
+					
+					# Build the graph from all targets in the selection
+					# The selection contains all targets loaded from packages
+					selection.targets.each do |name, target|
+						target.dependencies.each do |dependency|
+							dependency_name = dependency.name.to_s
+							
+							# Create edge from target to its dependency
+							if dependency.private?
+								lines << "    #{sanitize_id(name)}[#{name}] -.-> #{sanitize_id(dependency_name)}[#{dependency_name}]"
+							else
+								lines << "    #{sanitize_id(name)}[#{name}] --> #{sanitize_id(dependency_name)}[#{dependency_name}]"
+							end
+						end
+					end
+					
+					diagram = lines.join("\n")
 					
-					chain = chain.partial(provider)
+					if output_path = @options[:output_path]
+						File.write(output_path, diagram)
+					else
+						$stdout.puts diagram
+					end
+					
+					return diagram
 				end
 				
-				visualization = ::Build::Dependency::Visualization.new
+				private
 				
-				graph = visualization.generate(chain)
+				# Convert a name to a valid Mermaid node ID.
+				# @parameter name [String] The name to sanitize.
+				# @returns [String] A sanitized identifier safe for use in Mermaid diagrams.
+				def sanitize_id(name)
+					name.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+				end
+			end
+			
+			# Visualize file-level dependencies from the build graph.
+			class Files < Selection
+				self.description = "Visualize file-level dependencies by walking the build graph."
 				
-				if output_path = @options[:output_path]
-					Graphviz.output(graph, path: output_path, format: :svg)
-				else
-					$stdout.puts graph.to_dot
+				options do
+					option "-o/--output-path <path>", "The output path for the visualization."
 				end
 				
-				return graph
+				# Process and generate the file dependency visualization.
+				# @parameter selection [Select] The selection to visualize.
+				# @returns [String] The generated Mermaid diagram.
+				def process(selection)
+					require "build/graph/walker"
+					require "build/graph/visualization"
+					
+					context = selection.context
+					chain = selection.chain
+					environment = context.configuration.environment
+					
+					# Build the controller to get the root nodes
+					controller = ::Build::Controller.build(limit: 1) do |builder|
+						builder.add_chain(chain, [], environment)
+					end
+					
+					# Create a process group for task execution
+					group = ::Process::Group.new
+					
+					# Create a walker that traverses without building
+					walker = ::Build::Graph::Walker.new do |walker, node, parent_task = nil|
+						task_class = node.task_class(parent_task) || ::Build::Graph::Task
+						task = task_class.new(walker, node, group)
+						
+						# Use traverse instead of visit to skip building:
+						task.traverse
+					end
+					
+					# Populate the walker by traversing from the root nodes
+					walker.update(controller.nodes)
+					
+					# Generate the Mermaid diagram
+					visualization = ::Build::Graph::Visualization.new
+					diagram = visualization.generate(walker)
+					
+					if output_path = @options[:output_path]
+						File.write(output_path, diagram)
+					else
+						$stdout.puts diagram
+					end
+					
+					return diagram
+				end
+			end
+			
+			nested :command, {
+				"packages" => Packages,
+				"targets" => Targets,
+				"files" => Files,
+			}, default: "packages"
+			
+			# Delegate context to parent Top command.
+			# @returns [Context] The project context.
+			def context
+				parent.context
+			end
+			
+			# Execute the visualize command.
+			def call
+				@command.call
 			end
 		end
 	end

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}"