litbuild 1.0.11 → 1.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 450a93fb7a60735ed6618b58aff828dd2c6a8846b7664e7916df70ca319f1f4c
-  data.tar.gz: 0f7523cd36707b6748f868b6229d69413874503282511929891e1d4ea344d8df
+  metadata.gz: c8e6cf1338409a6f92412c572ddca22dfea69dec035c023ec029aa73b56f833f
+  data.tar.gz: 9fe0eb1366a7404cfe258081c3ef4f3f96e5214cba7f6d428dceac520d35da0f
 SHA512:
-  metadata.gz: '08ee5269104135777fb2dd06c225b03854b8b38c61723c0652b98aebc1fef19cad4ded3267249312e8821de764fab8360189216bf50e6b039f442a48cc9ed169'
-  data.tar.gz: 4626ce942e4afd88bca32d3613488bd2ac509107c90f467ae0deb3f14c0086ff6fd401647a9173ab5906284a042422802c0dc0fb067e80645217cf70e98e4686
+  metadata.gz: 6f79a4716874345084ec1ac7fe7c41049cd09db46d46e7349125767a9598b7a079314dac3630fcc221c0365a0a6bdb033bede9a1c41ce772b5740e01c15b3a53
+  data.tar.gz: e4db23446ce1334ec23ad2e1b566195ca0eb3515cbf7876089498f144af5e9e92302b87ec8ad9c6495c61935d4dfc90b5803acb979b603cddbbefcc8890e4054

data/lib/litbuild/ascii_doc_visitor.rb

@@ -285,14 +285,14 @@ module Litbuild
     def write_parameter(doc, params)
       params.each do |param|
         pname = param['name'].first
-        pdefault = param['default'].first.gsub(/\\\n  /, '')
+        pdefault = param['default'].first.gsub(/[\\\s]+/m, ' ')
         default_string = if pdefault == '(empty)'
                            'not set'
                          else
                            "`#{pdefault}`"
                          end
 
-        value = @parameters[pname].gsub(/\\\n  /, '')
+        value = @parameters[pname].gsub(/[\\\s]+/m, ' ')
         val_string = if value == ''
                        'not set'
                      else

data/lib/litbuild/bash_script_visitor.rb

@@ -167,9 +167,14 @@ module Litbuild
       script.string
     end
 
+    # Timestamps are written with default format plus
+    # seconds-since-epoch (in parentheses), to make it as easy as
+    # possible to calculate how long things take.
+    DATECMD = "date '+%a %b %e %H:%M:%S %Z %Y (%s)'"
+
     def write_components(location:, script:)
       @written[location].map do |target|
-        script.puts("echo \"At $(date): Beginning #{target}:\"")
+        script.puts("echo \"At $(#{DATECMD}): Beginning #{target}:\"")
         script.puts("./#{target}")
       end
     end
@@ -339,7 +344,7 @@ module Litbuild
       render_restart_header(script, restart_file, package.version, pkgusr_dir)
       pkgusr_srcdir = File.join(pkgusr_dir, package.name_and_version)
       render_add_package_user(package, script, log)
-      @scm.copy_source_files_commands(package).each do |cp_command|
+      @scm.copy_files_commands(package).each do |cp_command|
         render_command(script, cp_command, log)
       end
       script.puts("export LB_SOURCE_DIR=#{quote(pkgusr_srcdir)}")
@@ -505,8 +510,7 @@ module Litbuild
     def render_service_pipeline(script, spipe)
       pname = spipe['name'].first
       spipe['bundle']&.each do |bundle|
-        script.puts("grep -q '^#{pname}$' #{bundle}/contents || " \
-                    "echo #{pname} >> #{bundle}/contents")
+        render_add_to_bundle(script, bundle, pname)
       end
       sdirs = spipe['servicedirs']
       sdirs.each_with_index do |sdir, i|
@@ -527,17 +531,12 @@ module Litbuild
 
     def render_service_dir(script, sdir)
       sd = ServiceDir.new(sdir)
-      if sd.bundle
-        script.puts("grep -q '^#{sd.name}$' #{sd.bundle}/contents || " \
-                    "echo #{sd.name} >> #{sd.bundle}/contents")
-      end
+      render_add_to_bundle(script, sd.bundle, sd.name) if sd.bundle
       script.puts("mkdir -p #{sd.name}")
       sd.oneline_files.keys.sort.each do |fn|
         script.puts("echo #{sd.oneline_files[fn]} > #{sd.name}/#{fn}")
       end
       multiline = sd.multiline_files
-      deps = sd.dependencies
-      multiline['dependencies'] = [deps.join("\n")] unless deps.empty?
       multiline.keys.sort.each do |filename|
         # I always terminate here documents in litbuild-generated
         # scripts with "LBEOF", partly because I'm thinking "Litbuild
@@ -555,9 +554,22 @@ module Litbuild
           script.puts("echo '#{env[envvar]}' > #{sd.name}/env/#{envvar}")
         end
       end
+      unless sd.dependencies.empty?
+        script.puts("mkdir -p #{sd.name}/dependencies.d")
+        sd.dependencies.each do |dep|
+          script.puts("touch #{sd.name}/dependencies.d/#{dep}")
+        end
+      end
       skip_line(script)
     end
 
+    def render_add_to_bundle(script, bundle, svc)
+      script.puts("mkdir -p #{bundle}")
+      script.puts("echo bundle > #{bundle}/type")
+      script.puts("mkdir -p #{bundle}/contents.d")
+      script.puts("touch #{bundle}/contents.d/#{svc}")
+    end
+
     def render_cfgrepo_trailer(script, blueprint, log)
       cfgs = blueprint['configuration-files']
       return unless cfgs

data/lib/litbuild/blueprint.rb

@@ -9,13 +9,15 @@ require 'litbuild/visitor'
 module Litbuild
   # Blueprints are described in the `doc` directory.
   #
-  # tl;dr: Blueprints are considered as "chunks" separated by blank
-  # lines. Each chunk can be either directives or narrative. Narrative
-  # is AsciiDoc and does not get parsed or transformed. Directives are
-  # basically a simplified version of YAML.
+  # tl;dr:
   #
-  # After parsing, the narrative is found in the `grafs` variables and
-  # directives are found in `directive` hashes.
+  # Blueprints are considered as "chunks" separated by blank lines.
+  # Each chunk can be either directives or narrative.
+  # Narrative is AsciiDoc and does not get parsed or transformed.
+  # Directives are basically a simplified version of YAML.
+  #
+  # After parsing, the narrative is found in the `grafs` variables
+  # and directives are found in `directive` hashes.
   class Blueprint
     class << self
       # This should simply be the name of the directory where blueprints
@@ -31,45 +33,29 @@ module Litbuild
       ObjectSpace.each_object(Class).select { |c| c < self }
     end
 
-    # WARNING: in most cases, a freshly-created blueprint cannot be used
-    # until it has also been _prepared_. (See below.)
-    def initialize(text:)
-      parser = BlueprintParser.new(text)
+    def initialize(text:, parameters:, logfile_namer:, library:)
+      parser = BlueprintParser.new(file_text: text, parameters: parameters)
       @base_directives = parser.base_directives
       @phase_directives = parser.phase_directives
       @base_grafs = parser.base_grafs
       @phase_grafs = parser.phase_grafs
       @active_phase = @base_directives['default-phase']&.first
-    end
-
-    # This prepares a blueprint for use. This is separate from
-    # initialize because parameters are not available until after all
-    # blueprints have been parsed, and the logfile namer is not
-    # available until after the LOGFILE_DIR parameter can be resolved.
-    #
-    # Parameters is a set of configuration parameters
-    # Logfile_namer is used to generate log file names
-    # Library is the BlueprintLibrary, used (for example) to find
-    # dependencies.
-    def prepare(parameters:, logfile_namer:, library:)
       @logfile_namer = logfile_namer
       @bp_library = library
-      [@base_directives,
-       @phase_directives,
-       @base_grafs,
-       @phase_grafs].each { |component| resolve_all(parameters, component) }
     end
 
-    # Dependencies need to be handled before their dependants; that's
-    # handled here. Subclasses should run `super` before doing anything
-    # else with the Visitor, or call the send_to_dependencies method
-    # directly, so that this happens properly!
+    # Dependencies need to be rendered before their dependants;
+    # that's handled here.
+    # Subclasses should run `super` before doing anything else
+    # with the Visitor,
+    # or call the send_to_dependencies method directly,
+    # so that this happens properly!
     def accept(visitor:)
       send_to_dependencies(visitor: visitor)
     end
 
-    # Return a copy of this blueprint that is initialized to operate on
-    # the specified phase.
+    # Return a copy of this blueprint
+    # that is initialized to operate on the specified phase.
     def for_phase(new_active_phase)
       return self unless phases?
 
@@ -102,10 +88,11 @@ module Litbuild
       directives[directive]
     end
 
-    # This is just like the [] operator method except that it always
-    # returns only the first value for a directive -- which is helpful
-    # for all the directives that are only ever supposed to have a
-    # single value, like `name` or `full-name`.
+    # This is just like the [] operator method except that
+    # it always returns only the first value for a directive --
+    # which is helpful for all the directives that
+    # are only ever supposed to have a single value,
+    # like `name` or `full-name`.
     def value(directive)
       self[directive]&.first
     end
@@ -147,24 +134,6 @@ module Litbuild
       @logfile_namer.path_for(name, phase, stage_name)
     end
 
-    def parameter_defaults
-      values = {}
-      all_directive_sets = [@base_directives, @phase_directives.values].flatten
-      all_directive_sets.each do |dirset|
-        next unless dirset.key?('parameter')
-
-        dirset['parameter'].each do |a_param|
-          val = a_param['default'].first
-          values[a_param['name'].first] = if val == '(empty)'
-                                            ''
-                                          else
-                                            val
-                                          end
-        end
-      end
-      values
-    end
-
     def target_name
       if active_phase
         "#{name}::#{active_phase}"
@@ -181,9 +150,11 @@ module Litbuild
       'FAILURE'
     end
 
-    # If a dependency is declared both without a phase (typically in the
-    # base directives for the blueprint) and with a phase (typically in
-    # a phase of that blueprint), throw away the phaseless declaration
+    # If a dependency is declared both without a phase
+    # (typically in the base directives for the blueprint)
+    # and with a phase
+    # (typically in # a phase of that blueprint),
+    # throw away the phaseless declaration
     # to avoid including two versions of the dependency.
     def deduped_dependency_names
       dep_names = self['depends-on'].clone || []
@@ -210,29 +181,5 @@ module Litbuild
 
       @active_phase = phase
     end
-
-    private
-
-    def resolve_all(parameters, something)
-      case something
-      when Hash
-        something.each_value { |element| resolve_all(parameters, element) }
-      when Array
-        something.each { |element| resolve_all(parameters, element) }
-      when String
-        resolve(parameters: parameters, a_string: something)
-      end
-    end
-
-    def resolve(parameters:, a_string:)
-      params = a_string.scan(/PARAM\[([A-Z_]+)\]/).flatten.sort.uniq
-      params.each do |p|
-        parameters[p] ||
-          raise(ParameterMissing, "Parameter #{p} is not defined")
-
-        a_string.gsub!(/PARAM\[#{p}\]/, parameters[p])
-      end
-      a_string
-    end
   end
 end

data/lib/litbuild/blueprint_library.rb

@@ -4,12 +4,15 @@ require 'litbuild/commands'
 require 'litbuild/narrative'
 require 'litbuild/package'
 require 'litbuild/section'
+require 'litbuild/blueprint_parser'
 
 module Litbuild
   # BlueprintLibrary initializes and sets configuration parameters for
-  # blueprints, and provides a common access point for blueprints and
-  # parameters. It always loads blueprints from the *current working
-  # directory* and uses config parameters from *the environment*.
+  # blueprints,
+  # and provides a common access point for blueprints and parameters.
+  # It always loads blueprints from the *current working directory*
+  # and uses config parameters from *the environment*
+  # (or the default values defined in blueprints).
   class BlueprintLibrary
     REQUIRED_PARAMS = %w[DOCUMENT_DIR LOGFILE_DIR PATCH_DIR
                          SCRIPT_DIR TARFILE_DIR WORK_SITE].freeze
@@ -17,17 +20,8 @@ module Litbuild
     attr_reader :blueprints, :parameters
 
     def initialize(logfile_namer_class:)
-      @blueprints = {}
-      Blueprint.descendants.each do |blueprint_type|
-        load_blueprints_of_type(blueprint_type)
-      end
       @parameters = resolve_parameter_values
-      log_namer = logfile_namer_class.new(@parameters['LOGFILE_DIR'])
-      @blueprints.each_value do |bp|
-        bp.prepare(parameters: @parameters,
-                   logfile_namer: log_namer,
-                   library: self)
-      end
+      @blueprints = load_and_parse_all_blueprints(logfile_namer_class)
     end
 
     def blueprint_for(target:)
@@ -39,8 +33,10 @@ module Litbuild
     end
 
     # Convert the dependency declarations found in a `depends-on`
-    # directive to actual blueprints. See the `Dependencies` section of
-    # doc/blueprints.txt for details on how this works.
+    # directive to actual blueprints
+    # (from the blueprint library).
+    # See the `Dependencies` section of doc/blueprints.txt
+    # for details on how this is supposed to work.
     def dependencies_for(blueprint)
       dep_names = blueprint.deduped_dependency_names
       dep_names.map do |dep|
@@ -59,8 +55,8 @@ module Litbuild
 
     private
 
-    # split a target name, like linux::headers, into a blueprint name
-    # (linux) and a phase name (headers).
+    # split a target name, like linux::headers,
+    # into a blueprint name (linux) and a phase name (headers).
     def split_name_and_phase(target:)
       if target.include?('::')
         target.strip.match(/(.*)::(.*)/)[1..2]
@@ -69,54 +65,94 @@ module Litbuild
       end
     end
 
-    # These methods are used during initialization, be cautious when
-    # modifying them.
+    # These methods are used during initialization,
+    # be cautious when modifying them.
 
-    def load_blueprints_of_type(blueprint_type)
-      # Sometimes, starting in ruby 2.3, there is an extra singleton
-      # descendant of Blueprint, or something. (This happens about a
-      # thrid of the time, so I really mean "soemtime"s.) IDK what's
-      # going on and I don't feel like fussing with it; this kludge
-      # works around the issue, whatever it is.
-      return unless blueprint_type.name
+    def blueprint_files_by_type
+      fbt = {}
+      Blueprint.descendants.each do |bptype|
+        fbt[bptype] = Dir.glob("./#{bptype.directory_name}/*.txt")
+      end
+      fbt
+    end
 
-      # All blueprints have a name and a full-name. If a blueprint has
-      # no `name:` or `full-name:` directive, they will be provided at
-      # load time.
-      automatic_directives = %w[name full-name]
+    def load_and_parse_all_blueprints(logfile_namer_class)
+      log_namer = logfile_namer_class.new(@parameters['LOGFILE_DIR'])
 
-      Dir.glob("./#{blueprint_type.directory_name}/*.txt").each do |a_file|
-        bp_text = File.read(a_file)
-        begin
-          automatic_directives.each do |directive|
-            unless bp_text.match?(/^#{directive}:/)
-              bp_text = "#{directive}: #{File.basename(a_file, '.txt')}\n\n" +
-                        bp_text
+      blueprints = {}
+      blueprint_files_by_type.each do |bp_type, bp_files|
+        bp_files.each do |bp_file|
+          bp_text = load_and_add_automatic_directives(bp_file)
+          begin
+            bp = bp_type.new(text: bp_text, parameters: @parameters,
+                             logfile_namer: log_namer, library: self)
+            if blueprints[bp.name]
+              raise(DuplicateBlueprint,
+                    "Duplicate blueprint #{bp.name} found in #{bp_file}")
             end
+            blueprints[bp.name] = bp
+          rescue ArgumentError => e
+            raise(Litbuild::ParseError,
+                  "Could not parse #{bp_file}}: #{e.message}")
           end
-          bp = blueprint_type.new(text: bp_text)
-        rescue ArgumentError => e
-          raise(Litbuild::ParseError, "Could not parse #{a_file}: #{e.message}")
-        end
-        if @blueprints[bp.name]
-          raise(DuplicateBlueprint,
-                "Duplicate blueprint #{bp.name} found in #{a_file}")
-        else
-          @blueprints[bp.name] = bp
         end
       end
+      blueprints
+    end
+
+    # All blueprints have a name and a full-name.
+    # If a blueprint has no `name:` or `full-name:` directive,
+    # they will be provided at load time
+    # (the basename of the blueprint file is used for either
+    # or both missing directives)
+    def load_and_add_automatic_directives(filename)
+      text = File.read(filename)
+      name = File.basename(filename, '.txt')
+      automatic_directives = %w[name full-name]
+      automatic_directives.each do |dir|
+        text = "#{dir}: #{name}\n\n" + text unless text.match?(/^#{dir}:/)
+      end
+      text
+    end
+
+    # This does an initial parse of blueprints that declare parameters,
+    # and returns just the result of parsing those declarations.
+    def parameters_from(blueprint_text)
+      lines = blueprint_text.lines
+
+      return {} unless lines.detect { |l| l.start_with?('parameter:') }
+
+      # For purposes of finding parameters, phases, parameter
+      # references for substitution, and conditional blocks are
+      # irrelevant.
+      simplified = lines.grep_v(/^phase:/).grep_v(/^#/).join
+      simplified.gsub!(/PARAM\[[A-Z_]+\]/, 'UNSET')
+
+      parser = BlueprintParser.new(file_text: simplified)
+      param_directives = parser.base_directives['parameter']
+      params = {}
+      param_directives.each do |a_param|
+        default_val = a_param['default'].first
+        params[a_param['name'].first] = if default_val == '(empty)'
+                                          ''
+                                        else
+                                          default_val.gsub(/[\\\s]+/m, ' ')
+                                        end
+      end
+      params
     end
 
     def resolve_parameter_values
-      values = {}
-      REQUIRED_PARAMS.each { |key| values[key] = 'UNSET' }
-      @blueprints.each_value do |bp|
-        values.merge!(bp.parameter_defaults)
+      params = {}
+      REQUIRED_PARAMS.each { |key| params[key] = 'UNSET' }
+      bp_files = blueprint_files_by_type.values.flatten
+      bp_files.each do |bp_file|
+        params.merge!(parameters_from(File.read(bp_file)))
       end
       ENV.each do |k, v|
-        values[k] = v if values.key?(k)
+        params[k] = v if params.key?(k)
       end
-      @parameters = values
+      @parameters = params
     end
   end
 end

data/lib/litbuild/blueprint_parser.rb

@@ -5,36 +5,53 @@ require 'litbuild/string_indentation'
 require 'json'
 
 module Litbuild
-  # This is a kludgy hand-built parser. Blueprint structure is not (at
-  # least, at this point) complicated enough that I can see any point in
-  # defining a grammar and using a parser generator. The structure of
-  # blueprints is described informally in `doc/blueprints.txt` (and
-  # blueprint-type-specific files under `doc` as well).
+  # This is a kludgy hand-built parser,
+  # written by someone who does not know how to write parsers.
+  # Blueprint structure is not
+  # (at least, at this point)
+  # complicated enough that I can see any point in defining a grammar
+  # and using a parser generator.
+  # The structure of blueprints,
+  # and the intended behavior of this parser,
+  # are described informally in
+  # `doc/blueprints.txt`
+  # (and blueprint-type-specific files under `doc` as well).
+  #
+  # The entire parse process occurs during initialization,
+  # so after creating a BlueprintParser you will either be able
+  # to ask it for the result of the parse operation,
+  # or have an exception to deal with.
+  #
+  # Essentially all methods are therefore used within initialization.
+  # Use great care when modifying this class!
   class BlueprintParser
     include StringIndentation
 
-    # _directives_ are for use in scripts. _grafs_ are for use in
-    # documents.
+    # _directives_ are for use in scripts.
+    # _grafs_ are for use in documents.
     attr_reader :base_directives, :phase_directives, :base_grafs, :phase_grafs
 
-    def initialize(file_text)
-      @text = file_text
+    def initialize(file_text:, parameters: nil)
+      @text = file_text.dup
+      substitute_parameters(parameters) if parameters
+      resolve_conditional_blocks if @text.match?(/^#IF /)
+
       @phase_directives = {}
       @phase_grafs = {}
       phase_chunks = @text.split(/^phase: ([a-z -_]+)$/)
 
-      # The first part of the blueprint, before any phase directive,
-      # becomes the base directives and base narrative for the
-      # blueprint. If there are no phase directives, this is the entire
-      # blueprint, obvs.
+      # The first part of the blueprint,
+      # before any phase directive,
+      # becomes the base directives and base narrative for the blueprint.
+      # If there are no phase directives, this is the entire blueprint.
       @base_grafs = []
       @base_directives = parse_phase(phase_chunks.shift, {}, @base_grafs)
       @base_directives['full-name'] ||= @base_directives['name']
 
-      # The rest of the blueprint, if any, consists of directives and
-      # narrative for specific phases. The directives for each phase
-      # include all the base directives, as well as those specific to
-      # the phase.
+      # The rest of the blueprint, if any, consists of directives
+      # and narrative for specific phases.
+      # The directives for each phase include all the base directives,
+      # as well as those specific to the phase.
       until phase_chunks.empty?
         phase_name = phase_chunks.shift
         phase_contents = phase_chunks.shift
@@ -45,9 +62,9 @@ module Litbuild
         @phase_grafs[phase_name] = grafs
       end
 
-      # Any directives at the beginning of a blueprint are actually a
-      # file header that should not be considered as part of the
-      # narrative for it.
+      # Any directives at the beginning of a blueprint are
+      # actually a file header
+      # that should not be considered as part of the narrative for it.
       @base_grafs.shift while @base_grafs[0].is_a?(Hash)
     rescue StandardError => e
       msg = "Cannot parse blueprint starting: #{@text.lines[0..3].join}"
@@ -56,9 +73,51 @@ module Litbuild
 
     private
 
-    # Parse all directive paragraphs found in blueprint_text. Also add
-    # all parsed directive paragraphs, and all narrative paragraphs, to
-    # a collecting parameter.
+    # Find all `PARAM[parameter_name]` patterns in the text to parse.
+    # Replace each pattern with the parameter value.
+    #
+    # This must be done before anything else so that the conditional
+    # block conditions can be evaluated.
+    def substitute_parameters(parameters)
+      to_substitute = @text.scan(/PARAM\[([A-Z_]+)\]/).flatten.sort.uniq
+      to_substitute.each do |p|
+        @text.gsub!(/PARAM\[#{p}\]/, parameters[p])
+      end
+    end
+
+    # Find all #IF ... #ENDIF blocks.
+    # For each one, either remove it entirely,
+    # or remove the #IF and #ENDIF lines and leave the block.
+    def resolve_conditional_blocks
+      lines = @text.lines
+      resolved = []
+      in_conditional_block = false
+      condition_is_true = nil
+      lines.each do |line|
+        if in_conditional_block
+          if line.match?(/^#ENDIF/)
+            in_conditional_block = false
+            condition_is_true = nil
+          elsif condition_is_true
+            resolved << line
+          end
+          next
+        end
+        if line.match?(/^#IF/)
+          in_conditional_block = true
+          left, right = /^#IF (.*) = (.*)$/.match(line)[1..2]
+          condition_is_true = (left == right)
+          next
+        end
+        resolved << line
+      end
+      @text = resolved.join
+    end
+
+    # Parse all directive paragraphs found in blueprint_text.
+    # Also add all parsed directive paragraphs,
+    # and all narrative paragraphs,
+    # to a collecting parameter.
     def parse_phase(blueprint_text, start_with_directives, graf_collector)
       directives = JSON.parse(JSON.generate(start_with_directives))
       paragraphs = blueprint_text.split(/\n\n+/m)
@@ -76,8 +135,8 @@ module Litbuild
     end
 
     # All s6-rc service directories should be tracked in the
-    # configuration file repository, so add them to
-    # `configuration-files`.
+    # configuration file repository,
+    # so add them to `configuration-files`.
     def handle_servicedirs(directives)
       cfgs = directives['configuration-files'] || []
       if (spipes = directives['service-pipeline'])
@@ -114,6 +173,8 @@ module Litbuild
       graf_directives = Hash.new { |h, k| h[k] = [] }
       until lines_to_process.empty?
         directive_line = lines_to_process.shift
+        next if directive_line.empty?
+
         md = /^([A-Za-z0-9_-]+): *(.*)/.match(directive_line)
         unless md
           raise(Litbuild::ParseError,
@@ -134,11 +195,12 @@ module Litbuild
     end
 
     # Regardless of what kind of directive structure we're dealing with,
-    # all of the lines that are indented more than the initial directive
-    # line are part of that directive.  This method finds all those
-    # related lines and strips away the common initial indentation; it
-    # returns both the related lines and the amount of indentation that
-    # was removed.
+    # all lines that are indented more than the initial directive line
+    # are part of that directive.
+    # This method finds all those related lines
+    # and strips away the common initial indentation;
+    # it returns both the related lines
+    # and the amount of indentation that was removed.
     def related_lines(directive_line, lines_to_process)
       directive_indent = indent_for(directive_line)
       related = []
@@ -149,9 +211,11 @@ module Litbuild
       strip_indentation_from_array(related)
     end
 
-    # What kind of directive are we dealing with? Could be a simple
-    # value (with zero or more continuation lines), or a multiline
-    # value, or an array, or a subdirective block.
+    # What kind of directive are we dealing with?
+    # Could be a simple value (with zero or more continuation lines),
+    # or a multiline value,
+    # or an array,
+    # or a subdirective block.
     def parse_directive_value(firstline_value, other_lines, indentation)
       if firstline_value == '|'
         multiline_value(other_lines, indentation)
@@ -167,20 +231,25 @@ module Litbuild
     end
 
     # any time a directive line is indented more than the previous line,
-    # without being a part of an array or sub-directive or multi-line
-    # directive, it's a continuation of the previous line.
+    # without being a part of an array
+    # or sub-directive
+    # or multi-line
+    # directive,
+    # it's a continuation of the previous line.
     def folded_continuation_lines(first_line, related)
       stripped = related.map(&:strip)
       stripped.unshift(first_line)
       stripped.join(" \\\n  ")
     end
 
-    # While parsing multiline values, we want to restore the indentation
-    # that was previously stripped away -- this is typically used for
-    # `file` directives, which often appear in multiple directive blocks
-    # and should be treated as a whole. The indentation for multi-line
-    # values must be removed *later*, during rendering of scripts and
-    # documents.
+    # While parsing multiline values,
+    # we want to restore the indentation
+    # that was previously stripped away --
+    # this is typically used for `file` directives,
+    # which often appear in multiple directive blocks
+    # and should be treated as a whole.
+    # The indentation for multi-line values must be removed *later*,
+    # during rendering of scripts and documents.
     def multiline_value(lines, indentation)
       lines_with_indentation = lines.map { |l| (' ' * indentation) + l }
       "#{lines_with_indentation.join("\n")}\n"
@@ -199,9 +268,10 @@ module Litbuild
       raise(Litbuild::ParseError, "Problem parsing: #{lines}")
     end
 
-    # It turns out that sub-directives are the easiest thing in the
-    # world to parse, since we can just take the value and parse it as a
-    # new directive block.
+    # It turns out that sub-directives are
+    # the easiest thing in the world to parse,
+    # since we can just take the value
+    # and parse it as a new directive block.
     def subdirective_value(lines)
       parse_lines(lines)
     end

data/lib/litbuild/driver.rb

@@ -16,9 +16,6 @@ module Litbuild
   # All the actual work is done by Visitors that are handed to the
   # top-level blueprint target (typically specified on the command line).
   class Driver
-    REQUIRED_PARAMS = %w[DOCUMENT_DIR LOGFILE_DIR PATCH_DIR
-                         SCRIPT_DIR TARFILE_DIR WORK_SITE].freeze
-
     def initialize(logfile_namer_class: Litbuild::LogfileNamer)
       @bplib = BlueprintLibrary.new(logfile_namer_class: logfile_namer_class)
     end

data/lib/litbuild/package.rb

@@ -16,7 +16,7 @@ module Litbuild
       'packages'
     end
 
-    def initialize(text:)
+    def initialize(text:, parameters:, logfile_namer:, library:)
       super
       if phases?
         phases.each do |p|
@@ -131,11 +131,16 @@ module Litbuild
         end
 
         # otherwise, the default version goes right *before* the *first
-        # directive of the next stage* (which will always be present).
+        # directive of the next stage* (which *should* always be present)...
         next_stage = STAGE_DIRECTIVES[STAGE_DIRECTIVES.index(stg) + 1]
         first_idx = grafs.index do |graf|
           graf.respond_to?(:key) && graf.key?(next_stage)
         end
+
+        # ...but if, for whatever reason, we haven't found a place to
+        # put the default directives, just put them at the beginning.
+        first_idx ||= 0
+
         grafs.insert(first_idx, stg => to_add[stg])
       end
     end

data/lib/litbuild/source_code_manager.rb

@@ -13,7 +13,8 @@ module Litbuild
   #
   # Note, SourceCodeManager does not recurse into additional levels of
   # subdirectories -- it turns out that makes the test suite really
-  # slow.
+  # slow, and recursive search is not useful to me, so I'm just
+  # skipping it.
   class SourceCodeManager
     def initialize(*dirs)
       all_pkgfiles = dirs.map do |d|
@@ -55,13 +56,39 @@ module Litbuild
     end
 
     ##
-    # Package Users expect to have tarfiles for the top-level package
-    # and any in-tree packages in their `src` directory, and patches in
-    # their `patches` directory. This produces commands that copy needed
-    # files from the TARFILE_DIR and PATCH_DIR to those directories, if
-    # not already present there.
-    def copy_source_files_commands(package)
+    # Typically, Package Users expect to have tarfiles for the top-level
+    # package and any in-tree packages in their `src` directory, and
+    # patches in their `patches` directory. This method arranges things
+    # that way: it produces commands that copy all the necessary files
+    # from TARFILE_DIR and/or PATCH_DIR to the destination directory,
+    # skipping any that are already present where the Package Users
+    # build script expects to find them.
+    #
+    # Binary package files are an exception to the typical case. A
+    # binary package file has name `binary-#{packagename}.tar.lz` (no
+    # version number, and always lzip-compressed), and contains the
+    # files produced by the compilation and installation process. If
+    # such a file is present in the Package User home directory, the
+    # build script simply unpacks it and does nothing else.
+    #
+    # So: if a binary package file is present in the tarfile directory,
+    # this method simply emits a command to copy it to the Package User
+    # home directory; and if there is already a binary package file
+    # present in the Package User home directory, this method does
+    # nothing.
+    def copy_files_commands(package)
       pkgusr = pkgusr_name(package)
+
+      # copy binary file if available, then return
+      binfile = "binary-#{package.name}.tar.lz"
+      return ["cp #{find_file(binfile)} ~#{pkgusr}"] \
+        if @available_files.detect { |f| /#{binfile}/ =~ f }
+
+      # do nothing if binary file is present in home dir already
+      return [] if homedir(package) && File.exist?(
+        File.join(homedir(package), binfile)
+      )
+
       mkdir_commands = %w[src patches].map do |dir|
         "mkdir -p ~#{pkgusr}/#{dir}"
       end

data/lib/litbuild/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Litbuild
-  VERSION = '1.0.11'
+  VERSION = '1.0.16'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litbuild
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.16
 platform: ruby
 authors:
 - Brett Neumeier
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-19 00:00:00.000000000 Z
+date: 2023-11-18 00:00:00.000000000 Z
 dependencies: []
 description: A build system based on Knuth's idea of literate programming.
 email:
@@ -63,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: A literate build system