Created portfolio tasks.rake file and moved common Rake code from profile & CRD tasks.rake into it.

Author: james-ball-qualcomm

.github/workflows/pages.yml

@@ -76,19 +76,19 @@ jobs:
       - name: Copy RVI20 Profile Release PDF
         run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVI20.pdf
       - name: Create MC100-32 PDF Spec
-        run: ./do gen:proc_cert_model_pdf[MC100-32]
+        run: ./do gen:proc_crd_pdf[MC100-32]
       - name: Copy MC100-32 PDF
         run: cp gen/crd/pdf/MC100-32.pdf _site/pdfs/MC100-32.pdf
       - name: Create MC100-32 HTML Spec
-        run: ./do gen:proc_cert_model_html[MC100-32]
+        run: ./do gen:proc_crd_html[MC100-32]
       - name: Copy MC100-32 HTML
         run: cp gen/crd/html/MC100-32.html _site/htmls/MC100-32.html
       - name: Create MC100-64 PDF Spec
-        run: ./do gen:proc_cert_model_pdf[MC100-64]
+        run: ./do gen:proc_crd_pdf[MC100-64]
       - name: Copy MC100-64 PDF
         run: cp gen/crd/pdf/MC100-64.pdf _site/pdfs/MC100-64.pdf
       - name: Create MC100-64 HTML Spec
-        run: ./do gen:proc_cert_model_html[MC100-64]
+        run: ./do gen:proc_crd_html[MC100-64]
       - name: Copy MC100-64 HTML
         un: cp gen/crd/html/MC100-64.html _site/htmls/MC100-64.html
       - name: Copy manual html

.github/workflows/regress.yml

@@ -131,7 +131,7 @@ jobs:
         name: Build container
         run: ./bin/build_container
       - name: Generate extension PDF
-        run: ./do gen:proc_cert_model_pdf[MockProcCertModel]
+        run: ./do gen:proc_crd_pdf[MockProcCertModel]
   regress-gen-profile:
     runs-on: ubuntu-latest
     needs: regress-smoke

.gitignore

@@ -17,4 +17,3 @@ _site
 images
 *.bak
 *.log
-*.bak

.vscode/launch.json

@@ -6,7 +6,7 @@
       "name": "MC100-32",
       "request": "launch",
       "command": "bundle exec rake",
-      "script": "gen:proc_cert_model_pdf[MC100-32]",
+      "script": "gen:proc_crd_pdf[MC100-32]",
       "args": [],
       "askParameters": false
     },
@@ -15,7 +15,7 @@
       "name": "MC200-32",
       "request": "launch",
       "command": "bundle exec rake",
-      "script": "gen:proc_cert_model_pdf[MC200-32]",
+      "script": "gen:proc_crd_pdf[MC200-32]",
       "args": [],
       "askParameters": false
     },

backends/crd/tasks.rake

@@ -1,48 +1,38 @@
 # frozen_string_literal: true
+#
+# Contains Rake rules to generate adoc, PDF, and HTML for a CRD.
 
 require "pathname"
 
-require "asciidoctor-pdf"
-require "asciidoctor-diagram"
-
-require_relative "#{$lib}/idl/passes/gen_adoc"
-
-puts "UPDATE: Inside crd tasks.rake"
-
 CERT_DOC_DIR = Pathname.new "#{$root}/backends/crd"
 
 Dir.glob("#{$root}/arch/proc_cert_model/*.yaml") do |f|
-  proc_cert_model_name = File.basename(f, ".yaml")
-  proc_cert_model_obj = YAML.load_file(f, permitted_classes: [Date])
-  proc_cert_class_name = File.basename(proc_cert_model_obj['class']['$ref'].split("#")[0], ".yaml")
-  raise "Ill-formed processor certificate model file #{f}: missing 'class' field" if proc_cert_model_obj['class'].nil?
+  model_name = File.basename(f, ".yaml")
+  model_obj = YAML.load_file(f, permitted_classes: [Date])
+  class_name = File.basename(model_obj['class']['$ref'].split("#")[0], ".yaml")
+  raise "Ill-formed processor certificate model file #{f}: missing 'class' field" if model_obj['class'].nil?
 
-  file "#{$root}/gen/crd/adoc/#{proc_cert_model_name}.adoc" => [
+  file "#{$root}/gen/crd/adoc/#{model_name}.adoc" => [
     __FILE__,
-    "#{$root}/arch/proc_cert_class/#{proc_cert_class_name}.yaml",
-    "#{$root}/arch/proc_cert_model/#{proc_cert_model_name}.yaml",
+    "#{$root}/arch/proc_cert_class/#{class_name}.yaml",
+    "#{$root}/arch/proc_cert_model/#{model_name}.yaml",
     "#{$root}/lib/arch_obj_models/certificate.rb",
     "#{$root}/lib/arch_obj_models/portfolio.rb",
     "#{$root}/lib/portfolio_design.rb",
     "#{$root}/lib/design.rb",
     "#{CERT_DOC_DIR}/templates/crd.adoc.erb"
   ] do |t|
-    # Ensure that unconfigured resolved architecture called "_" exists.
-    Rake::Task["#{$root}/.stamps/resolve-_.stamp"].invoke
-
-    # Create architecture object so we can have it create the ProcCertModel.
-    # Use the unconfigured resolved architecture called "_".
-    arch = Architecture.new("RISC-V Architecture", $root / "gen" / "resolved_arch" / "_")
+    arch = pf_create_arch
 
     # Create ProcCertModel for specific processor certificate model as specified in its arch YAML file.
     # The Architecture object also creates all other portfolio-related class instances from their arch YAML files.
     # None of these objects are provided with a Design object when created.
-    puts "UPDATE: Creating ProcCertModel for #{proc_cert_model_name}"
-    proc_cert_model = arch.proc_cert_model(proc_cert_model_name)
+    puts "UPDATE: Creating ProcCertModel for #{model_name}"
+    proc_cert_model = arch.proc_cert_model(model_name)
 
-    puts "UPDATE: Creating PortfolioDesign using processor certificate model #{proc_cert_model_name}"
     # Create the one PortfolioDesign object required for the ERB evaluation.
-    portfolio_design = PortfolioDesign.new(proc_cert_model_name, arch, [proc_cert_model])
+    puts "UPDATE: Creating PortfolioDesign using processor certificate model #{model_name}"
+    portfolio_design = PortfolioDesign.new(model_name, arch, [proc_cert_model])
 
     # Create empty binding and then specify explicitly which variables the ERB template can access.
     # Seems to use this method name in stack backtraces (hence its name).
@@ -57,104 +47,63 @@ Dir.glob("#{$root}/arch/proc_cert_model/*.yaml") do |f|
     erb_binding.local_variable_set(:proc_cert_model, proc_cert_model)
     erb_binding.local_variable_set(:portfolio, proc_cert_model)
 
-    template_path = Pathname.new("#{CERT_DOC_DIR}/templates/crd.adoc.erb")
-    erb = ERB.new(File.read(template_path), trim_mode: "-")
-    erb.filename = template_path.to_s
-
-    FileUtils.mkdir_p File.dirname(t.name)
-
-    # Convert ERB to final ASCIIDOC. Note that this code is broken up into separate function calls
-    # each with a variable name to aid in running a command-line debugger on this code.
-    puts "UPDATE: Converting ERB template to adoc for #{proc_cert_model_name}"
-    erb_result = erb.result(erb_binding)
-    erb_result_monospace_converted_to_links = portfolio_design.find_replace_links(erb_result)
-    erb_result_with_links_added = portfolio_design.find_replace_links(erb_result_monospace_converted_to_links)
-    erb_result_with_links_resolved = AsciidocUtils.resolve_links(erb_result_with_links_added)
-
-    File.write(t.name, erb_result_with_links_resolved)
-    puts "UPDATE: Generated adoc source at #{t.name}"
+    pf_create_adoc("#{CERT_DOC_DIR}/templates/crd.adoc.erb", erb_binding, t.name, portfolio_design)
   end
 
-  file "#{$root}/gen/crd/pdf/#{proc_cert_model_name}.pdf" => [
+  file "#{$root}/gen/crd/pdf/#{model_name}.pdf" => [
     __FILE__,
-    "#{$root}/gen/crd/adoc/#{proc_cert_model_name}.adoc"
+    "#{$root}/gen/crd/adoc/#{model_name}.adoc"
   ] do |t|
-    adoc_file = "#{$root}/gen/crd/adoc/#{proc_cert_model_name}.adoc"
-    FileUtils.mkdir_p File.dirname(t.name)
-    sh [
-      "asciidoctor-pdf",
-      "-w",
-      "-v",
-      "-a toc",
-      "-a compress",
-      "-a pdf-theme=#{$root}/ext/docs-resources/themes/riscv-pdf.yml",
-      "-a pdf-fontsdir=#{$root}/ext/docs-resources/fonts",
-      "-a imagesdir=#{$root}/ext/docs-resources/images",
-      "-r asciidoctor-diagram",
-      "-r #{$root}/backends/ext_pdf_doc/idl_lexer",
-      "-o #{t.name}",
-      adoc_file
-    ].join(" ")
-    puts "UPDATE: Generated PDF at #{t.name}"
+    pf_adoc2pdf("#{$root}/gen/crd/adoc/#{model_name}.adoc", t.name)
   end
 
-  file "#{$root}/gen/crd/html/#{proc_cert_model_name}.html" => [
+  file "#{$root}/gen/crd/html/#{model_name}.html" => [
     __FILE__,
-    "#{$root}/gen/crd/adoc/#{proc_cert_model_name}.adoc"
+    "#{$root}/gen/crd/adoc/#{model_name}.adoc"
   ] do |t|
-    adoc_file = "#{$root}/gen/crd/adoc/#{proc_cert_model_name}.adoc"
-    FileUtils.mkdir_p File.dirname(t.name)
-
-    puts "UPDATE: Generating PDF at #{t.name}"
-    sh [
-      "asciidoctor",
-      "-w",
-      "-v",
-      "-a toc",
-      "-a imagesdir=#{$root}/ext/docs-resources/images",
-      "-b html5",
-      "-r asciidoctor-diagram",
-      "-r #{$root}/backends/ext_pdf_doc/idl_lexer",
-      "-o #{t.name}",
-      adoc_file
-    ].join(" ")
-    puts "UPDATE: Generated PDF at #{t.name}"
+    pf_adoc2html("#{$root}/gen/crd/adoc/#{model_name}.adoc", t.name)
   end
 end
 
 namespace :gen do
   desc <<~DESC
-    Generate certificate documentation for a specific version as a PDF.
+    Generate CRD (Certification Requirements Document) as a PDF.
 
     Required options:
-      proc_cert_model_name - The key of the certification model under arch/proc_cert_model
+      model_name - The name of the certification model under arch/proc_cert_model
   DESC
-  task :proc_cert_model_pdf, [:proc_cert_model_name] do |_t, args|
-    proc_cert_model_name = args[:proc_cert_model_name]
-    if proc_cert_model_name.nil?
-      warn "Missing required option: 'proc_cert_model_name'"
+  task :proc_crd_pdf, [:model_name] do |_t, args|
+    model_name = args[:model_name]
+    if model_name.nil?
+      warn "Missing required option: 'model_name'"
       exit 1
     end
 
-    unless File.exist?("#{$root}/arch/proc_cert_model/#{proc_cert_model_name}.yaml")
-      warn "No certification model named '#{proc_cert_model_name}' found in arch/proc_cert_model"
+    unless File.exist?("#{$root}/arch/proc_cert_model/#{model_name}.yaml")
+      warn "No certification model named '#{model_name}' found in arch/proc_cert_model"
       exit 1
     end
 
-    Rake::Task["#{$root}/gen/crd/pdf/#{proc_cert_model_name}.pdf"].invoke
+    Rake::Task["#{$root}/gen/crd/pdf/#{model_name}.pdf"].invoke
   end
 
-  task :proc_cert_model_html, [:proc_cert_model_name] do |_t, args|
-    if args[:proc_cert_model_name].nil?
-      warn "Missing required option: 'proc_cert_model_name'"
+  desc <<~DESC
+    Generate CRD (Certification Requirements Document) as an HTML file.
+
+    Required options:
+      model_name - The name of the certification model under arch/proc_cert_model
+  DESC
+  task :proc_crd_html, [:model_name] do |_t, args|
+    if args[:model_name].nil?
+      warn "Missing required option: 'model_name'"
       exit 1
     end
 
-    unless File.exist?("#{$root}/arch/proc_cert_model/#{args[:proc_cert_model_name]}.yaml")
-      warn "No certification model named '#{args[:proc_cert_model_name]}' found in arch/proc_cert_model"
+    unless File.exist?("#{$root}/arch/proc_cert_model/#{args[:model_name]}.yaml")
+      warn "No certification model named '#{args[:model_name]}' found in arch/proc_cert_model"
       exit 1
     end
 
-    Rake::Task["#{$root}/gen/crd/html/#{args[:proc_cert_model_name]}.html"].invoke
+    Rake::Task["#{$root}/gen/crd/html/#{args[:model_name]}.html"].invoke
   end
 end

backends/portfolios/tasks.rake

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# Contains common methods called from portfolio-based tasks.rake files.
+
+require "pathname"
+require "asciidoctor-pdf"
+require "asciidoctor-diagram"
+require_relative "#{$lib}/idl/passes/gen_adoc"
+
+# @return [Architecture]
+def pf_create_arch
+  # Ensure that unconfigured resolved architecture called "_" exists.
+  Rake::Task["#{$root}/.stamps/resolve-_.stamp"].invoke
+
+  # Create architecture object so we can have it create the ProcCertModel.
+  # Use the unconfigured resolved architecture called "_".
+  Architecture.new("RISC-V Architecture", $root / "gen" / "resolved_arch" / "_")
+end
+
+# @param erb_template_pname [String] Path to ERB template file
+# @param erb_binding [Binding] Path to ERB template file
+# @param target_pname [String] Full name of adoc file being generated
+# @param portfolio_design [PortfolioDesign] Portfolio design being generated
+def pf_create_adoc(erb_template_pname, erb_binding, target_pname, portfolio_design)
+  template_path = Pathname.new(erb_template_pname)
+  erb = ERB.new(File.read(template_path), trim_mode: "-")
+  erb.filename = template_path.to_s
+
+  FileUtils.mkdir_p File.dirname(target_pname)
+
+  # Convert ERB to final ASCIIDOC. Note that this code is broken up into separate function calls
+  # each with a variable name to aid in running a command-line debugger on this code.
+  puts "UPDATE: Converting ERB template to adoc for #{portfolio_design.name}"
+  erb_result = erb.result(erb_binding)
+  erb_result_monospace_converted_to_links = portfolio_design.find_replace_links(erb_result)
+  erb_result_with_links_added = portfolio_design.find_replace_links(erb_result_monospace_converted_to_links)
+  erb_result_with_links_resolved = AsciidocUtils.resolve_links(erb_result_with_links_added)
+
+  File.write(target_pname, erb_result_with_links_resolved)
+  puts "UPDATE: Generated adoc in #{target_pname}"
+end
+
+# @param adoc_file [String] Full name of source adoc file
+# @param target_pname [String] Full name of PDF file being generated
+def pf_adoc2pdf(adoc_file, target_pname)
+  FileUtils.mkdir_p File.dirname(target_pname)
+
+  puts "UPDATE: Generating PDF in #{target_pname}"
+  sh [
+    "asciidoctor-pdf",
+    "-w",
+    "-v",
+    "-a toc",
+    "-a compress",
+    "-a pdf-theme=#{$root}/ext/docs-resources/themes/riscv-pdf.yml",
+    "-a pdf-fontsdir=#{$root}/ext/docs-resources/fonts",
+    "-a imagesdir=#{$root}/ext/docs-resources/images",
+    "-r asciidoctor-diagram",
+    "-r #{$root}/backends/ext_pdf_doc/idl_lexer",
+    "-o #{target_pname}",
+    adoc_file
+  ].join(" ")
+  puts "UPDATE: Generated PDF in #{target_pname}"
+end
+
+# @param adoc_file [String] Full name of source adoc file
+# @param target_pname [String] Full name of HTML file being generated
+def pf_adoc2html(adoc_file, target_pname)
+  FileUtils.mkdir_p File.dirname(target_pname)
+
+  puts "UPDATE: Generating HTML in #{target_pname}"
+  sh [
+    "asciidoctor",
+    "-w",
+    "-v",
+    "-a toc",
+    "-a imagesdir=#{$root}/ext/docs-resources/images",
+    "-r asciidoctor-diagram",
+    "-r #{$root}/backends/ext_pdf_doc/idl_lexer",
+    "-o #{target_pname}",
+    adoc_file
+  ].join(" ")
+  puts "UPDATE: Generated HTML in #{target_pname}"
+end