litbuild 1.0.21 → 1.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22c6c387b304ec0c1abb563a8cb3f5a8812a52433c82a2cc9c4322e202b6ea65
-  data.tar.gz: e590d33d71e4c70a7a4411f67b11d17fb46f8c4846b6c1ac4fdae91dfc9205e5
+  metadata.gz: cce41178693bb69ed91330ddebbedeb7db27b71263c52e9841010e328e2e9b05
+  data.tar.gz: 05de3849a236d875dd817b829f37fc461f177fa38860002a39a9e3f8f6db3845
 SHA512:
-  metadata.gz: 3fd317ab3c29b1b37ddac395ba27ab95d304c4b052c80bebab9250acb60b11946e51f432fdc39c761a392a0d96714a21981c5adfbd726c0654d30b520ad33eb5
-  data.tar.gz: 37e5f89cce214d9a2fcd4ce4ce44b00aa44d5da9cfc6ce564f7a142c9b2c8bdde1eeeb822b2e125e3a3b450bb78db61017f9eaa94b400baa0668699be29dba8a
+  metadata.gz: 8a658ecf5db92962af7f400e343017b6018ba70b1992a026f60dc7d6949762b749655eafe2fe1d8d3eb109ad23da5ad2db4510c17c712d02f6fecd5c96475944
+  data.tar.gz: e190668e4fcca7ccdebc422ae33d8b202777ec0d82887af45de2c3041d74e9f92f16148063f36770531a88e572192e2ea3d80a3ab333a18fb3c881da1ac41266

data/README

@@ -5,58 +5,62 @@ The idea of literate programming was invented by Donald Knuth. The basic
 notion -- at least, the way I think of it -- is that the _primary_ users
 of the source code of a program are the people who are reading the
 source code to acquire an understanding of how it works (often, because
-they want to modify it), and that the transformation of the source code
+they want to modify it); and that the transformation of the source code
 into an executable program that can be run, or the actual use of that
 program, is a _secondary_ purpose of the code.
 
-Because of this prioritization, most of the attention and energy
-invested in writing the program is in a narrative discussion of how the
-program works and what the purpose of each component (function
-declaration, subroutine or coroutine, or whatever) is within that
-narrative.
+Because of this ranking of priorities, when writing a program in
+literate programming style, most of the attention and energy is invested
+in a narrative discussion of how the program works and what the purpose
+of each component (function declaration, subroutine or coroutine, or
+whatever) is within that narrative.
 
 Automated build tools -- such as make, maven, and jam -- are great,
-because they allow developers on a project to focus their attention on
-the project codebase _per se,_ and let the build system worry about how
-to compile and test it. There are lots of build tools, reflecting a wide
-variety of design goals and value systems. Regardless of which tool is
-used, though, I have noticed that once a software project reaches a
-certain level of complexity, the automated build becomes similarly
-complex -- to the point that it is a major undertaking to figure out how
-it actually works.
+because they allow developers working on a project to focus their
+attention on the project codebase _per se,_ and let the build system
+worry about how to compile and test it. There are lots of build tools,
+reflecting a wide variety of design goals and value systems. Regardless
+of which tool is used, though, I have noticed that once a software
+project reaches a certain level of complexity, the build process becomes
+similarly complex -- to the point that it is a major undertaking to
+figure out how it actually works.
 
 That makes it difficult to diagnose and correct problems with the build
-system when they arise, for the same reason that any other
-incomprehensible software code is hard to work with effectively... and
-since nobody pays any attention to the build machinery until it stops
-working for some reason, I've also noticed that it's common for everyone
-on a team or project to forget how it works in between those times. At
-best, there's one person who knows how it all works, and he or she gets
-saddled with the job of fixing it or tweaking it when that's necessary.
+system when they arise, for the same reasons that any other
+incomprehensible code is hard to work with effectively... and I've also
+noticed that, in most cases, nobody pays any attention to the build
+machinery until it stops working for some reason, with the result that
+it's common for everyone on a team or project to have forgotten how the
+build system works by the point that something goes wrong and it needs
+to be repaired or modified. At best, there's one person who knows how it
+all works, and he or she gets saddled with the job of fixing it or
+tweaking it when that's necessary.
 
 Litbuild is an attempt to bring together the ideas of literate
-programming and automated build tools. My goal is to make it easy to
-write build scripts in such a way that they _tell a story_ about how to
-build a project (regardless of how big or complex that project is),
-focusing primarily on describing that build process with enough clarity
-that other people can understand it -- while still providing enough
-structure to that story that the litbuild system can produce scripts
-that will perform an automated build of the project.
+programming and automated build tools.
+
+My goal is to make it easy to write build scripts in such a way that
+they _tell a story_ about how to build a project (regardless of how big
+or complex that project is), focusing primarily on describing that build
+process with enough clarity that other people can understand it -- while
+still providing enough structure to that story that the litbuild system
+can produce scripts that will perform an automated build of the project.
 
 The original literate programming systems, WEB and CWEB, have two modes
 of operation: you can run the literate source code through a `tangle`
 program to produce source code in a traditional programming language
 like Pascal or C (which you can then feed to a compiler to produce a
 program), or you can run it through a `weave` program that produces
-document source (which you can send through a typesetting system like
+document source (which you can process using a typesetting system like
 TeX or Docbook).
 
-Litbuild is essentially a processor for a domain-specific language. It
-takes, as input, human-readable files -- referred to as "blueprints" --
-that consist of narrative text written with AsciiDoc markup,
-interspersed with command blocks and other directives, just like the
-literate source in WEB and CWEB. Litbuild has a simpler interface,
-though: when it is run, it always generates both a set of bash scripts
+Litbuild is simpler; it has only one mode of operation. It takes, as
+input, human-readable files -- referred to as "blueprints" -- that
+consist of narrative text interspersed with command blocks and other
+directives, just like the literate source in WEB and CWEB. In the case
+of litbuild, the narrative text is written in AsciiDoc, and the command
+blocks and other directives are mostly shell commands. When litbuild
+processes a set of blueprints, it generates both a set of bash scripts
 that will execute the actual build process and _also_ AsciiDoc-formatted
 documentation files that can be run through a document production
 toolchain to produce HTML or PDF or whatever other documentation format
@@ -75,25 +79,25 @@ package installed...
 
 Or both!
 
+
 Using Litbuild
 ==============
 
 The litbuild gem provides a simple driver script, `lb`, that loads all
 the blueprint files it finds in a directory tree and then generates
-output files for the blueprint target specified on the command line. You
-can only specify one blueprint as a target; if you want more than one
-thing to be built, create a Section blueprint that talks about all the
-blueprints you want to build and how they fit together. If the target
-you want to build is a phase within a blueprint, specify it as
+output files for the blueprint target specified on the command line.
+
+You can only specify one blueprint as a target; if you want more than
+one thing to be built, create a Section blueprint that talks about all
+the blueprints you want to build and how they fit together. If the
+target you want to build is a phase within a blueprint, specify it as
 `blueprint::phase_name`; if the phase has a space in it, you can of
 course quote the command line argument like `"blueprint::phase name"`.
 
-Blueprints can refer to parameterized values. It is expected that
-default values for all these parameters will be provided (by convention,
-I generally put all the default values into a "configuration" narrative
-blueprint). To override any parameter value from the default, set an
-environment variable with its name before running the `lb` driver
-program.
+Blueprints can contain references to parameterized values. It is
+expected that default values for all these parameters will be provided
+in the blueprints. To override any parameter value, set an environment
+variable with its name before running the `lb` driver program.
 
 To use the lb driver to build a complete cross-toolchain as part of the
 Cross-Building Linux process, for example, you might use something like:
@@ -102,15 +106,15 @@ Cross-Building Linux process, for example, you might use something like:
 
 It's not strictly _necessary_ to use Section blueprints to perform a
 complete build for a complex target, because blueprints can specify what
-other bleuprints they depend on and litbuild will pull in whatever other
-blueprints are needed to resolve those dependencies. If all dependencies
-are correctly specified in all blueprints, all you really need to do is
-request the final target! But it's still a good idea to write a Section
-for any situation where the various components of a build story need to
-have an overall framing narrative or discussion to make them
-comprehensible, or when all the parts of a build need to share a common
-configuration or environment -- which is the case for most complicated
-processes.
+other blueprints they depend on and litbuild will pull in all the
+blueprints that are needed to resolve those dependencies. If all
+dependencies are correctly specified in all blueprints, all you really
+need to do is request the final target! But it's still a good idea to
+write a Section for any situation where the various components of a
+build story need to have an overall framing narrative or discussion to
+make them comprehensible, or when all the parts of a build need to share
+a common configuration or environment -- which is the case for most
+complicated processes.
 
 If any commands in the generated scripts appear to be run under `sudo`,
 litbuild has a feature that can help to run those scripts
@@ -122,13 +126,34 @@ with a full absolute path, or must exist in a specific set of default
 directories: /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, and
 /usr/local/sbin.
 
-Debugging Blueprints
-====================
+The AsciiDoc markup language supports "admonition" paragraphs, which are
+set apart from the rest of the narrative with distinctive formatting.
+There are a few styles of admonition defined in AsciiDoc: `NOTE`,
+`TIP`, `IMPORTANT`, `CAUTION`, and `WARNING`. Litbuild provides some
+extra visibility for `WARNING` admonitions: in addition to rendering
+them into the AsciiDoc output files, litbuild will write the text of
+these admonitions to the standard error stream as it processes them. If
+you're writing a blueprint, and you want to call the user's attention to
+something important even if they neglect to generate and read the
+resulting build narrative, you might find it helpful to include a
+`WARNING` admonition.
+
+(The support for WARNING admonitions works for single-paragraph
+admonitions where the paragraph starts with `WARNING:`, and it works for
+at least some admonition blocks with a `[WARNING]` label. If you want to
+use this feature, it's probably a good idea to try running litbuild on
+your blueprint(s) and make sure that the output is what you would like
+it to be.)
+
+
+Debugging Blueprints And Increasing Verbosity
+=============================================
 
 If litbuild is rejecting your blueprints with an error message and you
 can't figure out why, you can produce a great deal of debugging
 information by setting the environment variable RUBYOPT to `--debug`.
 
+
 Cross-Building Linux
 ====================
 
@@ -136,13 +161,13 @@ The litbuild program is developed in conjunction with a set of
 blueprints called "Cross-Building Linux," or CBL for short; this defines
 the build process used for Little Blue Linux. A lot of the features in
 litbuild are present for the convenience of CBL -- like the s6-rc
-service directory and pipeline logic, the ability to produce
+service directory and pipeline directives, the ability to produce
 package-user scripts, and the invocation of configuration file
 repository scripts. If you're using litbuild for some other purpose, and
 don't want to make use of those features, you might want to eliminate
 them.
 
-We're thinking of eventually rewriting litbuild as a C program to
-eliminate its dependency on ruby; if we do that, we'll probably provide
-a compile-time configuration option that allows features like these to
-be compiled out of the program.
+I'm thinking of eventually rewriting litbuild as a C program to
+eliminate its dependency on ruby; if I do that, perhaps I'll provide a
+compile-time configuration option that allows features like these to be
+compiled out of the program.

data/lib/litbuild/ascii_doc_visitor.rb

@@ -23,6 +23,7 @@ module Litbuild
       super(directory: @parameters['DOCUMENT_DIR'])
       @written = Hash.new { |hash, key| hash[key] = [] }
       @all_written_targets = []
+      @warnings = []
     end
 
     def visit_commands(commands:)
@@ -114,6 +115,10 @@ module Litbuild
       end
     end
 
+    def warning_admonitions
+      @warnings.empty? ? nil : @warnings.join("\n\n")
+    end
+
     private
 
     ##
@@ -193,11 +198,29 @@ module Litbuild
     def render_grafs(doc, grafs, block)
       grafs.each do |graf|
         case graf
-        when String then doc.puts(graf)
-        when Hash then handle_directives(doc, graf, block)
+        when String
+          doc.puts(graf)
+        when Hash
+          handle_directives(doc, graf, block)
         end
         doc.puts
       end
+      string_grafs = grafs.select { |graf| graf.is_a?(String) }
+      complex_warning_collector = nil
+      until string_grafs.empty?
+        graf = string_grafs.shift.strip
+        if complex_warning_collector
+          complex_warning_collector << graf
+          if graf.end_with?('====')
+            @warnings << complex_warning_collector.join("\n\n")
+            complex_warning_collector = nil
+          end
+        elsif graf.start_with?('WARNING:')
+          @warnings << graf
+        elsif graf.start_with?("[WARNING]\n")
+          complex_warning_collector = [graf]
+        end
+      end
     end
 
     ##
@@ -243,7 +266,9 @@ module Litbuild
     def write_servicepipe(doc, pipedefs)
       pipedefs.each do |pipedef|
         head = ".Service Pipeline: `#{pipedef['name'].first}`"
-        head += " (in bundle `#{pipedef['bundle'].first}`)" if pipedef['bundle']
+        unless pipedef['bundle'].empty?
+          head += " (in bundle `#{pipedef['bundle'].first}`)"
+        end
         doc.puts(head)
         doc.puts("[%autowidth,cols=\"d,d\",caption=]\n|===\n\n")
         pipedef['servicedirs'].each_with_index do |svcdir, idx|

data/lib/litbuild/bash_script_visitor.rb

@@ -18,6 +18,17 @@ module Litbuild
 
     INSTALL_GID = 9999
 
+    # 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)'"
+
+    # A set of standard program directories is used to find
+    # absolute paths.
+    SUDOPATH = %w[/bin /sbin
+                  /usr/bin /usr/sbin
+                  /usr/local/bin /usr/local/sbin].freeze
+
     attr_reader :blueprint_dir
 
     def initialize(parameters:)
@@ -27,8 +38,7 @@ module Litbuild
       @all_written_targets = []
       @all_commands = []
       @blueprint_dir = quote(File.expand_path('.'))
-      @scm = SourceCodeManager.new(@parameters['TARFILE_DIR'],
-                                   @parameters['PATCH_DIR'])
+      @scm = SourceCodeManager.new(@parameters['MATERIALS_DIR'])
     end
 
     def visit_commands(commands:)
@@ -121,10 +131,7 @@ module Litbuild
       skip_line(file)
       file.puts('if [ -n "$LITBUILDDBDIR" ]')
       file.puts('then')
-      file.puts('  if [ -d "${LITBUILDDBDIR}" -a -w "${LITBUILDDBDIR}" ]')
-      file.puts('  then')
-      file.puts('    mkdir -p "${LITBUILDDBDIR}/BUILD-LOG"')
-      file.puts('  fi')
+      file.puts('  mkdir -p "${LITBUILDDBDIR}/BUILD-LOG" || echo nevermind')
       file.puts('fi')
       skip_line(file)
       file.puts("begin_time=$(date '+%a %b %e %H:%M:%S %Z %Y (%s)')")
@@ -136,7 +143,7 @@ module Litbuild
       skip_line(file)
       file.puts("complete_time=$(date '+%a %b %e %H:%M:%S %Z %Y (%s)')")
       file.puts('complete_seconds=$(date +%s)')
-      file.puts('elapsed_time=$((complete_seconds - begin_seconds))')
+      file.puts('elapsed=$((complete_seconds - begin_seconds))')
       skip_line(file)
       bldir = '"${LITBUILDDBDIR}/BUILD-LOG"'
       file.puts("if [ -d #{bldir} -a -w #{bldir} ]")
@@ -145,7 +152,7 @@ module Litbuild
       file.puts("  echo 'Blueprint: #{target}' > $lbfile")
       file.puts('  echo "Started:   $begin_time" >> $lbfile')
       file.puts('  echo "Completed: $complete_time" >> $lbfile')
-      file.puts('  echo "Elapsed:   $elapsed_time" >> $lbfile')
+      file.puts('  echo "Elapsed:   $elapsed" >> $lbfile')
       write_toplevel_parameters(file)
       file.puts('fi')
       skip_line(file)
@@ -209,16 +216,15 @@ 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 $(#{DATECMD}): Beginning #{target}:\"")
+        script.puts('bp_begin=$(date +%s)')
         script.puts("./#{target}")
-        script.puts("echo \"At $(#{DATECMD}): Completed #{target}:\"")
+        script.puts('bp_comp=$(date +%s)')
+        script.puts('bp_elapsed=$((bp_comp - bp_begin))')
+        complete = "At $(#{DATECMD}): Completed #{target} ($bp_elapsed sec)"
+        script.puts("echo \"#{complete}\"")
       end
     end
 
@@ -236,15 +242,11 @@ module Litbuild
       end
     end
 
-    def running_as_root
+    def running_as_root?
       uid = `id -u`.strip
       uid == '0'
     end
 
-    SUDOPATH = %w[/bin /sbin
-                  /usr/bin /usr/sbin
-                  /usr/local/bin /usr/local/sbin].freeze
-
     def convert_to_absolute(command)
       return command if command.start_with?('/')
 
@@ -261,7 +263,7 @@ module Litbuild
     end
 
     def sudoers_entries
-      return [] if running_as_root
+      return [] if running_as_root?
 
       raw_sudo_cmds = @all_commands.select do |c|
         c.include?('sudo ') && c.lines.size < 2
@@ -415,8 +417,9 @@ module Litbuild
       if (aiar = package['after-install-as-root'])
         aiar.each { |cmd| render_command(script, cmd, log) }
       end
+      render_command(script, "cfggit add ~#{package.pkgusr_name}/options", log)
       render_cfgrepo_trailer(script, package, log)
-      render_command(script, 'set_install_dirs', log)
+      render_command(script, 'set-install-dirs', log)
       render_command(script, 'ldconfig', log)
     end
 
@@ -424,7 +427,7 @@ module Litbuild
       pkgusr = package.value('package-user')
       desc = pkgusr['description'].first || package.value('full_name')
       render_command(script,
-                     "add_package_user '#{desc}' #{package.pkgusr_name}",
+                     "add-package-user '#{desc}' #{package.pkgusr_name}",
                      log)
     end
 
@@ -631,13 +634,14 @@ module Litbuild
 
     # quote a string suitably for a bash script
     def quote(value)
-      # if value contains embedded backslash and newline characters, get
-      # rid of those first.
+      # if value contains embedded backslash and newline characters,
+      # get rid of those first.
       oneline = value.gsub(/\\\n  /m, '')
 
-      # now, if the value contains ' -- backslash-quote everything (incl spaces)
-      # if the value contains " -- single-quote the whole thing
-      # if the value contains other punctuation -- double-quote the whole thing
+      # now...
+      # if the value contains ': backslash-quote everything (incl spaces)
+      # if the value contains ": single-quote the whole thing
+      # if the value contains other punctuation: double-quote the whole thing
       case oneline
       when /'/
         oneline.gsub(/([\\ "'`$])/, '\\\\\1')

data/lib/litbuild/blueprint_library.rb

@@ -14,14 +14,17 @@ module Litbuild
   # 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
+    REQUIRED_PARAMS = %w[DOCUMENT_DIR LOGFILE_DIR MATERIALS_DIR
+                         SCRIPT_DIR WORK_SITE].freeze
 
     attr_reader :blueprints, :parameters
 
     def initialize(logfile_namer_class:)
+      warn('Resolving parameters') if $DEBUG
       @parameters = resolve_parameter_values
+      warn('Loading and parsing blueprints') if $DEBUG
       @blueprints = load_and_parse_all_blueprints(logfile_namer_class)
+      warn('Finished loading blueprints') if $DEBUG
     end
 
     def blueprint_for(target:)
@@ -81,11 +84,14 @@ module Litbuild
 
       blueprints = {}
       blueprint_files_by_type.each do |bp_type, bp_files|
+        warn("Parsing blueprints of type #{bp_type}") if $DEBUG
         bp_files.each do |bp_file|
+          warn("Parsing blueprint: #{bp_file}") if $DEBUG
           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)
+            warn("Parsed as #{bp.name}") if $DEBUG
             if blueprints[bp.name]
               raise(DuplicateBlueprint,
                     "Duplicate blueprint #{bp.name} found in #{bp_file}")
@@ -103,8 +109,8 @@ module Litbuild
     # 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)
+    # (the basename of the blueprint file is used for any
+    # missing directives)
     def load_and_add_automatic_directives(filename)
       text = File.read(filename)
       name = File.basename(filename, '.txt')

data/lib/litbuild/blueprint_parser.rb

@@ -27,10 +27,18 @@ module Litbuild
   class BlueprintParser
     include StringIndentation
 
-    # _directives_ are for use in scripts.
-    # _grafs_ are for use in documents.
+    # _directives_ are for use in scripts
+    # (and often are rendered in specific ways in documents).
+    # _grafs_ (short for "paragraphs") are for use only in documents.
     attr_reader :base_directives, :phase_directives, :base_grafs, :phase_grafs
 
+    # Litbuild actually creates two BlueprintParsers per blueprint:
+    # the first time, it is given only `file_text`,
+    # and the result of that operation is used to find parameters.
+    # Once all parameters have been found,
+    # another set of BlueprintParsers is created
+    # with both `file_text` and `parameters`.
+    #
     def initialize(file_text:, parameters: nil)
       @text = file_text.dup
       substitute_parameters(parameters) if parameters
@@ -43,7 +51,7 @@ module Litbuild
       # 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.
+      # (If there are no phase directives, that is the entire blueprint.)
       @base_grafs = []
       @base_directives = parse_phase(phase_chunks.shift, {}, @base_grafs)
       @base_directives['full-name'] ||= @base_directives['name']
@@ -62,10 +70,12 @@ module Litbuild
         @phase_grafs[phase_name] = grafs
       end
 
-      # Any directives at the beginning of a blueprint are
-      # actually a file header
+      # Any directives at the beginning of a blueprint
+      # constitute 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 Litbuild::Error => e
+      raise(e)
     rescue StandardError => e
       msg = "Cannot parse blueprint starting: #{@text.lines[0..3].join}"
       raise(Litbuild::ParseError, "#{msg} -- #{e}")
@@ -76,11 +86,15 @@ module Litbuild
     # 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.
+    # This must be done before anything else,
+    # so that any 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|
+        unless parameters[p]
+          msg = "Parameter \"#{p}\" is referenced but not defined."
+          raise(Litbuild::ParameterMissing, msg)
+        end
         @text.gsub!(/PARAM\[#{p}\]/, parameters[p])
       end
     end
@@ -134,7 +148,9 @@ module Litbuild
       directives
     end
 
-    # All s6-rc service directories should be tracked in the
+    # s6-rc service directories
+    # (if there are any)
+    # should be tracked in the
     # configuration file repository,
     # so add them to `configuration-files`.
     def handle_servicedirs(directives)
@@ -212,7 +228,8 @@ module Litbuild
     end
 
     # What kind of directive are we dealing with?
-    # Could be a simple value (with zero or more continuation lines),
+    # It could be a simple value
+    # (with zero or more continuation lines),
     # or a multiline value,
     # or an array,
     # or a subdirective block.
@@ -230,16 +247,35 @@ module Litbuild
       end
     end
 
-    # any time a directive line is indented more than the previous line,
+    # 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,
+    # or multi-line directive,
     # it's a continuation of the previous line.
+    # For AsciiDoc, we want to wind up with something
+    # formatted like the original,
+    # but will still work if copy-pasted into bash windows.
+    # So we'll embed backslashes at the end of each line,
+    #
+    # To make the indentation more-or-less correct,
+    # if something looks like a bash conditional statement or loop,
+    # we'll avoid indenting the relevant keyword lines,
+    # but add indentation back for other lines.
+    # This is somewhat naive and won't handle multiple-level
+    # complex statements correctly,
+    # but is better than nothing.
     def folded_continuation_lines(first_line, related)
+      keywords = %w[case do done elif else esac fi for if then while]
+
       stripped = related.map(&:strip)
       stripped.unshift(first_line)
-      stripped.join(" \\\n  ")
+      stripped.inject do |accum, line|
+        if keywords.any? { |word| line =~ /^#{word} ?/ }
+          "#{accum} \\\n#{line}"
+        else
+          "#{accum} \\\n  #{line}"
+        end
+      end
     end
 
     # While parsing multiline values,
@@ -248,6 +284,7 @@ module Litbuild
     # 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)

data/lib/litbuild/driver.rb

@@ -52,6 +52,7 @@ module Litbuild
       bp = library.blueprint_for(target: target)
       bp.accept(visitor: adv)
       adv.write_toplevel_doc(blueprint: bp)
+      $stderr.puts(adv.warning_admonitions) if adv.warning_admonitions
     end
 
     private

data/lib/litbuild/source_code_manager.rb

@@ -16,13 +16,17 @@ module Litbuild
   # 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|
-        Dir.glob("#{d}/*.tar*") +
-          Dir.glob("#{d}/*/*.tar*") +
-          Dir.glob("#{d}/*.patch*") +
-          Dir.glob("#{d}/*/*.patch*")
-      end.flatten
+    # there are a variety of common compression programs that might be
+    # used; the file extension can be used to figure out which program
+    # to use.
+    DECOMPRESSORS = { 'gz' => 'gzip', 'bz2' => 'bzip2', 'lzma' => 'lzma',
+                      'lz' => 'lzip', 'xz' => 'xz' }.freeze
+
+    def initialize(dir)
+      all_pkgfiles = (Dir.glob("#{dir}/*.tar*") +
+                       Dir.glob("#{dir}/*/*.tar*") +
+                       Dir.glob("#{dir}/*.patch*") +
+                       Dir.glob("#{dir}/*/*.patch*")).flatten
       abs_paths = all_pkgfiles.map { |f| File.expand_path(f) }
       @available_files = abs_paths.sort.uniq
     end
@@ -56,13 +60,13 @@ module Litbuild
     end
 
     ##
-    # 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.
+    # 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
+    # MATERIALS_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
@@ -117,7 +121,7 @@ module Litbuild
     end
 
     def find_file(filename)
-      @available_files.detect { |f| /#{filename}/ =~ f } ||
+      @available_files.detect { |f| %r{/#{filename}} =~ f } ||
         raise(Litbuild::MissingSource,
               "File #{filename} is needed but not available.")
     end
@@ -133,9 +137,6 @@ module Litbuild
       "tar -x #{decompress_opt} -f #{tarfile}"
     end
 
-    DECOMPRESSORS = { 'gz' => 'gzip', 'bz2' => 'bzip2', 'lzma' => 'lzma',
-                      'lz' => 'lzip', 'xz' => 'xz' }.freeze
-
     def decompressor_for_file(file)
       ext = DECOMPRESSORS.keys.find { |e| file =~ /#{e}$/ }
       ext ? DECOMPRESSORS[ext] : nil

data/lib/litbuild/string_indentation.rb

@@ -2,30 +2,26 @@
 
 module Litbuild
   module StringIndentation
-    # Utility method to find the amount of blank space at the beginning
-    # of a line.
+    # Find the amount of blank space at the beginning of a line.
     def indent_for(line)
       /^([[:blank:]]*).*/.match(line)[1].size
     end
 
-    # Utility method to strip the common indentation from all strings in
-    # an array. Returns both the stripped strings and the amount of
-    # indentation removed.
+    # Strip the common indentation from all strings in an array.
+    # Returns both the stripped strings and the amount of indentation removed.
     def strip_indentation_from_array(strings)
       common_indent = strings.map { |l| indent_for(l) }.min
       [strings.map { |l| l.slice(common_indent..-1) }, common_indent]
     end
 
-    # Utility method to strip the common indentation from all lines of a
-    # multi-line string. (Does not return the amount of indentation
-    # removed.)
+    # Strip the common indentation from all lines of a multi-line string.
+    # (This one does _not_ return the amount of indentation removed.)
     def strip_indentation_from_string(string)
       strip_indentation_from_array(string.lines)[0]
     end
 
-    # Utility method to strip the common indentation from all lines of a
-    # directive value (which is expected to be an array containing a
-    # single string element)
+    # Strip the common indentation from all lines of a directive value
+    # (which is expected to be an array containing a single string element)
     def strip_indentation_from_value(value)
       strip_indentation_from_string(value[0])
     end

data/lib/litbuild/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: litbuild
 version: !ruby/object:Gem::Version
-  version: 1.0.21
+  version: 1.0.27
 platform: ruby
 authors:
 - Brett Neumeier
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A build system based on Knuth's idea of literate programming.
 email:
@@ -48,7 +47,6 @@ licenses:
 - GPL-3.0-only
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -63,8 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A literate build system
 test_files: []