origen 0.38.0 → 0.40.0

data/origen_app_generators/lib/origen_app_generators/base.rb

@@ -0,0 +1,231 @@
+module OrigenAppGenerators
+  # This is the base generator used by all generators in this application
+  class Base < Origen::CodeGenerators::Base
+    include Origen::Utility::InputCapture
+
+    require 'gems'
+
+    def set_source_paths
+      # The base Origen generator puts the Origen core directory on the source path, in retrospect this
+      # was a bad idea and makes for hard to debug errors if an app generator resolves a template from
+      # outside of this app.
+      # So to keep things sane remove any inherited source paths.
+      self.class.source_paths.pop until self.class.source_paths.empty?
+      klass = self.class
+
+      until klass == OrigenAppGenerators::Base
+        if template_dir = OrigenAppGenerators.template_dirs[klass]
+          dir = []
+          last_class = nil
+          until klass.to_s =~ /^OrigenAppGenerators/
+            dir << "#{template_dir}/#{class_dir(klass)}"
+            last_class = klass
+            klass = klass.superclass
+          end
+          dir << "#{template_dir}/base"
+          klass = last_class
+        else
+          dir = "#{Origen.root!}/templates/app_generators/#{class_dir(klass)}"
+        end
+        Array(dir).each do |dir|
+          self.class.source_paths << dir if File.exist?(dir) && !self.class.source_paths.include?(dir)
+        end
+        klass = klass.superclass
+      end
+    end
+
+    # Just makes the type (:plugin or :application) available to all templates
+    def set_type
+      @type = type
+    end
+
+    def get_common_user_input
+      get_name_and_namespace
+    end
+
+    def get_lastest_origen_version
+      @latest_origen_version ||= begin
+        (Gems.info 'origen')['version']
+      rescue
+        # If the above fails, e.g. due to an SSL error in the runtime environment, try to fetch the
+        # latest Origen version from the Origen website, before finally falling back to the version
+        # we are currently running if all else fails
+        begin
+          require 'httparty'
+          response = HTTParty.get('http://origen-sdk.org/origen/release_notes/')
+          version = Origen::VersionString.new(response.body.match(/Tag: v(\d+\.\d+.\d+)</).to_a.last)
+          if version.valid?
+            version
+          else
+            fail "Can't get the latest version!"
+          end
+        rescue
+          Origen.version
+        end
+      end
+    end
+
+    protected
+
+    def class_dir(klass)
+      names = klass.to_s.split('::')
+      names.shift
+      names.map(&:underscore).join('/')
+    end
+
+    # def application_class?(klass)
+    #  until klass == OrigenAppGenerators::Base
+    # end
+
+    def debugger
+      require 'byebug'
+      byebug # rubocop:disable Lint/Debugger
+    end
+
+    def plugin?
+      type == :plugin
+    end
+
+    def application?
+      !plugin?
+    end
+
+    def self.title
+      desc.sub(/^An? /, '').titleize
+    end
+
+    # Calling this will compile all files in filelist against the current instance
+    # variable values
+    def build_filelist
+      symlink_cmds = []
+      self.destination_root = args.first
+      filelist.each do |_name, file|
+        if file[:type] == :symlink
+          if Origen.running_on_windows?
+            dest = Pathname.new("#{destination_root}/#{file[:dest]}")
+            source = dest.dirname.to_s + "/#{file[:source]}"
+            symlink_cmds << "call mklink /h #{dest.to_s.gsub('/', '\\')} #{source.to_s.gsub('/', '\\')}"
+          else
+            create_link file[:dest], file[:source]
+          end
+        elsif file[:type] == :dir || file[:type] == :directory
+          if file[:copy]
+            if (file.key? :dest) && (file.key? :source)
+              directory(file[:source], file[:dest])
+            else
+              directory(file[:dest] || file[:source])
+            end
+          elsif file[:nokeep]
+            empty_directory(file[:dest] || file[:source])
+          else
+            copy_file('dot_keep', "#{file[:dest]}/.keep")
+          end
+        else
+          dest = file[:dest] || file[:source]
+          if file[:copy] || dest =~ /.erb$/
+            copy_file(file[:source], dest)
+          else
+            @options = file[:options] || {}
+            template(file[:source], dest)
+          end
+        end
+      end
+      symlink_cmds.each { |cmd| system(cmd) }
+    end
+
+    # Convenience method that is equivalent to calling get_name and then get_namespace
+    def get_name_and_namespace
+      get_name
+      get_namespace
+    end
+
+    # Prompts the user to confirm or enter the Ruby namespace to be used in the app.
+    #
+    # If @name is already defined a proposal will be generated from that, alternatively a proposal
+    # can be supplied. If not proposal is resolved the user will be prompted to input from scratch.
+    def get_namespace(proposal = nil)
+      puts
+      puts "SELECT YOUR #{type.to_s.upcase}'S NAMESPACE"
+      puts
+      puts "All #{type} code needs to reside in a unique namespace, this prevents naming collisions with 3rd party plugins."
+      puts 'By Ruby conventions, this must start with a capital letter and should ideally be CamelCased and not use underscores.'
+      # puts 'Some examples:: C40TFSNVMTester, CAPIOrigen, LS2080, ApacheOrigen'
+      [@namespace_advice].each { |l| puts l } if @namespace_advice
+      puts
+      if !proposal && @name
+        proposal = @name.to_s.camelize
+      end
+      proposal = nil if proposal.length < 3
+
+      valid = false
+      until valid
+        @namespace = get_text(single: true, default: proposal)
+        proposal = nil
+        unless @namespace.empty?
+          if @namespace.length >= 3
+            valid = valid_constant?(@namespace)
+          end
+          unless valid
+            puts 'That namespace is not valid :-('
+            puts
+          end
+        end
+      end
+      @namespace
+    end
+
+    # Returns true if the given string can be converted to a valid Ruby constant and one that
+    # does not already exist within the scope of this application and Origen Core
+    def valid_constant?(string)
+      valid = false
+      # Try and convert this to a constant to test for validity, this will also screen things
+      # like Origen since that will not trigger an error
+      begin
+        string.constantize
+      rescue NameError => e
+        if e.message =~ /^uninitialized constant/
+          valid = true
+        end
+      else
+        # Something else is wrong with it
+      end
+      valid
+    end
+
+    # Prompts the user to input a name for the new application, this will be screened to ensure
+    # that it can cleanly cast to a symbol for use in Origen.
+    #
+    # This should be unique within the whole Origen ecosystem, in future this method will be enhanced
+    # to check with the Origen server which will in future maintain a database of known app names.
+    #
+    # The final name is returned at the end and assigned to variable @name for use in templates.
+    def get_name
+      proposal = args.first.symbolize.to_s
+      proposal = nil if proposal.length < 3
+      puts
+      puts "WHAT DO YOU WANT TO CALL YOUR NEW #{type.to_s.upcase}?"
+      puts
+      puts "This should be lowercased and underscored and will be used to uniquely identify your #{type} within the Origen ecosystem."
+      [@name_advice].each { |l| puts l } if @name_advice
+      puts
+      valid = false
+      until valid
+        name = get_text(single: true, default: proposal)
+        proposal = nil
+        unless name.empty?
+          if name == name.symbolize.to_s
+            if name.symbolize.to_s.length >= 3
+              valid = true
+              @name = name
+            end
+          else
+            puts
+            puts 'That name is not valid, how about this?'
+            proposal = name.symbolize.to_s
+          end
+        end
+      end
+      @name
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/empty_application.rb

@@ -0,0 +1,15 @@
+module OrigenAppGenerators
+  # Generates a generic application shell
+  class EmptyApplication < Application
+    # Any methods that are not protected will get invoked in the order they are
+    # defined when the generator is run
+
+    def generate_files
+      build_filelist
+    end
+
+    def conclude
+      puts "New app created at: #{destination_root}"
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/empty_plugin.rb

@@ -0,0 +1,15 @@
+module OrigenAppGenerators
+  # Generates a generic plugin shell
+  class EmptyPlugin < Plugin
+    # Any methods that are not protected will get invoked in the order they are
+    # defined when the generator is run
+
+    def generate_files
+      build_filelist
+    end
+
+    def conclude
+      puts "New app created at: #{destination_root}"
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/new.rb

@@ -0,0 +1,162 @@
+module OrigenAppGenerators
+  class New < Base
+    include Origen::Utility::InputCapture
+
+    desc 'Creates a new application generator within this application'
+
+    # Naming of this method is important here to override the default user input which
+    # does not apply to this generator
+    def get_common_user_input
+      get_domain
+      get_name
+      get_type
+      get_summary
+      @namespace = Origen.app.namespace
+    end
+
+    def set_type
+      # Type not applicable in for this generator
+    end
+
+    def generate_files
+      build_filelist
+    end
+
+    def enable
+      available = Origen.app.namespace.constantize::AVAILABLE
+      test_inputs = Origen.app.namespace.constantize::TEST_INPUTS
+
+      # **** Add require line ****
+      module_declaration = /\nmodule #{Origen.app.namespace}/
+      inject_into_file "lib/#{Origen.app.name}.rb", "require '#{Origen.app.name}/#{@domain_namespace.underscore}/#{@classname.underscore}'\n",
+                       before: module_declaration
+
+      # **** Add to the AVAILABLE hash ****
+      if available[@domain_summary]
+        existing_domain = /\s*('|")#{@domain_summary}('|") => \[\s*\n/
+        inject_into_file "lib/#{Origen.app.name}.rb", "      #{Origen.app.namespace}::#{@domain_namespace}::#{@classname},\n",
+                         after: existing_domain
+      else
+        new_domain = <<-END
+    '#{@domain_summary}' => [
+      #{Origen.app.namespace}::#{@domain_namespace}::#{@classname},
+    ],
+        END
+        available_hash = /AVAILABLE = {\s*\n/
+        inject_into_file "lib/#{Origen.app.name}.rb", new_domain, after: available_hash
+      end
+
+      # **** Add a starter set of test inputs ****
+      # First work out what the selection numbers will be for the new generator
+      if available[@domain_summary]
+        first = available.size - available.find_index { |k, _| k == @domain_summary }
+        second = available[@domain_summary].size
+      else
+        first = available.size + 1
+        second = 0
+      end
+      inputs = "\n    # #{test_inputs.size} - #{@domain_namespace}::#{@classname}\n"
+      if @parentclass == 'Plugin'
+        inputs += "    ['#{first}', '#{second}', :default, :default, 'A cool plugin', 'yes', :default]"
+      else
+        inputs += "    ['#{first}', '#{second}', :default, :default, :default]"
+      end
+      inputs = ",#{inputs}" unless test_inputs.empty?
+      end_of_test_inputs = /\n\s*\]\s*#\s*END_OF_TEST_INPUTS/
+      inject_into_file "lib/#{Origen.app.name}.rb", inputs, before: end_of_test_inputs
+    end
+
+    # Can't compile this as contains some final ERB, so substitute instead
+    # def customize_doc_page
+    #  file = filelist[:doc_info][:dest]
+    #  gsub_file file, 'TITLE_GOES_HERE', @title
+    #  if @type == :plugin
+    #    gsub_file file, 'INTRO_GOES_HERE', "This generates a customized version of the [Generic Plugin](<%= path 'origen_app_generators/plugin' %>)."
+    #  else
+    #    gsub_file file, 'INTRO_GOES_HERE', "This generates a customized version of the [Generic Application](<%= path 'origen_app_generators/application' %>)."
+    #  end
+    # end
+
+    def conclude
+      system "origen lint #{Origen.root}/lib/#{Origen.app.name}.rb"
+      puts
+      puts "New generator created at: #{filelist[:generator][:dest]}"
+      puts
+      puts "Create any template files you need for this generator in: #{filelist[:templates_dir][:dest]}"
+      puts
+      # puts "Before you go add some documentation about what this generates to: templates/web/origen_app_generators/origen_app_generators/#{@domain_namespace.underscore}/#{@classname.underscore}.md.erb"
+      # puts
+    end
+
+    protected
+
+    def get_summary
+      puts
+      puts 'DESCRIBE YOUR NEW GENERATOR IN A FEW WORDS'
+      puts
+      @summary = get_text(single: true)
+      @title = @summary.sub(/^An? /, '').titleize
+    end
+
+    def get_type
+      puts
+      puts 'WILL YOUR TEMPLATE GENERATE A PLUGIN OR A TOP-LEVEL APPLICATION?'
+      puts
+      type = get_text(single: true, accept: %w(application plugin)).downcase
+      @parentclass = type.capitalize
+    end
+
+    def get_name
+      puts
+      puts 'GIVE YOUR NEW GENERATOR CLASS A NAME'
+      puts
+      puts 'Your new generator needs a class name, this should be reasonably descriptive although it will not be displayed to end users'
+      puts 'Some examples: GenericTestBlock, IPBlock, MPGBOMApp'
+      puts
+      valid = false
+      until valid
+        @classname = get_text(single: true).split('::').last
+        unless @classname.empty?
+          if @classname.length >= 3
+            valid = valid_constant?("#{Origen.app.namespace}::#{@domain_namespace}::#{@classname}")
+          end
+          unless valid
+            puts 'That class name is not valid :-('
+            puts
+          end
+        end
+      end
+      @classname
+    end
+
+    def get_domain
+      puts
+      puts 'WHAT APPLICATION DOMAIN WILL YOUR NEW APP TEMPLATE APPLY TO?'
+      puts
+      puts "Enter something like 'Test Engineering', 'Design', etc."
+      puts
+      domain = get_text(single: true)
+      domain = domain.split(' ').map do |word|
+        # Ensure all first letters capitalized, but make sure something like
+        # 'NVM' remains 'NVM' and not 'Nvm'
+        letters = word.split('')
+        letters.first.upcase!
+        letters.join
+      end.join(' ')
+
+      @domain_summary = domain
+      @domain_namespace =  @domain_summary.gsub(' ', '')
+    end
+
+    def filelist
+      @filelist ||= {
+        generator:     { source: 'generator.rb',
+                         dest:   "lib/#{Origen.app.name}/#{@domain_namespace.underscore}/#{@classname.underscore}.rb" },
+        templates_dir: { dest: "templates/app_generators/#{@domain_namespace.underscore}/#{@classname.underscore}",
+                         type: :directory },
+        # doc_info:      { source: 'info.md.erb',
+        #                 dest:   "templates/web/#{Origen.app.name}/#{@domain_namespace.underscore}/#{@classname.underscore}.md.erb" }
+      }
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/origen_infrastructure/app_generator_plugin.rb

@@ -0,0 +1,109 @@
+module OrigenAppGenerators
+  module OrigenInfrastructure
+    # Generates a generic application shell
+    class AppGeneratorPlugin < Plugin
+      desc "A plugin to make your own application templates available through the 'origen new' command"
+
+      def initialize(*args)
+        @audience = :internal
+        @validate_release_tests = ['origen app_gen:test --regression']
+        super
+      end
+
+      # Any methods that are not protected will get invoked in the order that they are
+      # defined when the generator is run, method naming is irrelevant unless you want
+      # to override a method that is defined by the parent class
+
+      def get_user_input
+        # The methods to get the common user input that applies to all applications will
+        # get called at the start automatically, you have a chance here to ask any additional
+        # questions that are specific to the type of application being generated
+      end
+
+      def generate_files
+        @runtime_dependencies = [
+          ['origen_app_generators', ">= #{Origen.app!.version}"]
+        ]
+        @post_runtime_dependency_comments = [
+          'DO NOT ADD ANY ADDITIONAL RUNTIME DEPENDENCIES HERE, WHEN THESE GENERATORS',
+          'ARE INVOKED TO GENERATE A NEW APPLICATION IT WILL NOT BE LAUNCHED FROM WITHIN',
+          'A BUNDLED ENVIRONMENT.',
+          '',
+          'THEREFORE GENERATORS MUST NOT RELY ON ANY 3RD PARTY GEMS THAT ARE NOT',
+          'PRESENT AS PART OF A STANDARD ORIGEN INSTALLATION - I.E. YOU CAN ONLY RELY',
+          'ON THE GEMS THAT ORIGEN ITSELF DEPENDS ON.'
+        ]
+        # Calling this will build all files, directories and symlinks contained in the
+        # hash returned by the filelist method
+        build_filelist
+      end
+
+      def modify_files
+        # If you want to modify any of the generated files you can do so now, you have access
+        # to all of the Thor Action methods described here:
+        # http://www.rubydoc.info/github/wycats/thor/Thor/Actions
+        # See the enable method in lib/app_generators/new.rb for some examples of using these.
+      end
+
+      def conclude
+        # Print out anything you think the user should know about their new application at the end
+        puts "New app created at: #{destination_root}"
+        puts
+        puts 'Create your first generator by running this command within your new app:'
+        puts '  origen app_gen:new'
+        puts
+      end
+
+      protected
+
+      # Defines the filelist for the generator, the default list is inherited from the
+      # parent class (Plugin).
+      # The filelist can contain references to generate files, directories or symlinks in the
+      # new application.
+      #
+      # Generally to make your generator more maintainable try and re-use as much as possible
+      # from the parent generator, this means that your generator will automatically stay up
+      # to date with the latest conventions
+      #
+      # The master templates live in templates/app_generators/plugin, but
+      # DO NOT MODIFY THESE FILES DIRECTLY.
+      # Either add or remove things post-generation in the modify_files method or copy the
+      # master file to the equivalent sub-directory of templates/app_generators/origen_infrastructure_engineering/app_generator_plugin
+      # which will override the version in the master directory.
+      #
+      # Additional files can be added or removed from the filelist as shown below.
+      def filelist
+        @filelist ||= begin
+          list = super  # Always pick up the parent list
+          # Example of how to remove a file from the parent list
+          # list.delete(:web_doc_layout)
+          list.delete(:lib_readme)
+          list.delete(:lib_readme_dev)
+          list.delete(:templates_shared)
+          # Example of how to add a file, in this case the file will be compiled and copied to
+          # the same location in the new app
+          # list[:config_shared_commands] = { source: 'config/shared_commands.rb' }
+          list[:config_load_generators] = { source: 'config/load_generators.rb' }
+          list[:lib_base] = { source: 'lib/base.rb', dest: "lib/#{@name}/base.rb" }
+          list[:lib_plugin] = { source: 'lib/plugin.rb', dest: "lib/#{@name}/plugin.rb" }
+          list[:lib_application] = { source: 'lib/application.rb', dest: "lib/#{@name}/application.rb" }
+          # Alternatively specifying a different destination, typically you would do this when
+          # the final location is dynamic
+          # list[:gemspec] = { source: 'gemspec.rb', dest: "#{@name}.gemspec" }
+          # Example of how to create a directory
+          list[:templates_app] = { dest: 'templates/app_generators/application', type: :directory }
+          list[:templates_plugin] = { dest: 'templates/app_generators/plugin', type: :directory }
+          list[:templates_base] = { dest: 'templates/app_generators/base', type: :directory }
+          # By default, directories created in this way will contain a .keep file, to inhibit this:
+          # list[:pattern_dir] = { dest: "pattern", type: :directory, nokeep: true }
+          # Example of how to create a symlink
+          # list[:target_default] = { source: 'debug.rb',          # Relative to the file being linked to
+          #                          dest:   'target/default.rb', # Relative to destination_root
+          #                          type:   :symlink }
+          # Remember to return the final list
+          list
+        end
+      end
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/plugin.rb

@@ -0,0 +1,58 @@
+module OrigenAppGenerators
+  # The base generator class that should be used by all plugin generators
+  class Plugin < Application
+    def get_common_user_input
+      get_name_and_namespace
+      get_summary
+      get_audience unless @audience
+    end
+
+    protected
+
+    # See Application#filelist for more details
+    def filelist
+      @filelist ||= begin
+        list = super
+        list.delete(:web_doc_layout)
+        list.delete(:web_references)
+        list.delete(:web_defintions)
+        list.delete(:web_installation)
+        list.delete(:web_introduction)
+        list[:gemspec] = { source: 'gemspec.rb', dest: "#{@name}.gemspec" }
+        list[:templates_shared] = { dest: 'templates/shared', type: :directory }
+        if @audience == :external
+          list[:travis] = { source: '.travis.yml' }
+          list[:web_navbar] = { source: 'templates/web/partials/_navbar_external.html.erb', dest: 'templates/web/partials/_navbar.html.erb' }
+        else
+          list[:web_navbar] = { source: 'templates/web/partials/_navbar_internal.html.erb', dest: 'templates/web/partials/_navbar.html.erb' }
+        end
+        list[:lib_readme] = { source: 'lib/README', dest: "lib/#{@name}/README" }
+        list[:lib_readme_dev] = { source: 'lib_dev/README', dest: "lib/#{@name}_dev/README" }
+        list
+      end
+    end
+
+    def get_summary
+      puts
+      puts 'DESCRIBE YOUR NEW PLUGIN IN A FEW WORDS'
+      puts
+      @summary = get_text(single: true)
+    end
+
+    # Prompts the user to say whether the new plugin is intended for an internal
+    # or external audience (meaning it will published to rubygems.org)
+    def get_audience(proposal = nil)
+      puts
+      puts 'IS THIS PLUGIN GOING TO BE RELEASED TO AN EXTERNAL AUDIENCE?'
+      puts
+      puts 'By answering yes, this plugin will be pushed to rubygems.org when it is released and it will be available outside of your company.'
+      puts
+      confirm_external = get_text(confirm: :return_boolean, default: 'no')
+      @audience = :external if confirm_external
+    end
+
+    def type
+      :plugin
+    end
+  end
+end

data/origen_app_generators/lib/origen_app_generators/sub_block_parser.rb

@@ -0,0 +1,81 @@
+module OrigenAppGenerators
+  require 'strscan'
+  # Responsible for parsing something like this:
+  #
+  #   "ram, osc, pll, atd(2), comms[ram(2), osc](3)"
+  #
+  # into this:
+  #
+  #   {
+  #     "RAM"=>{}, "Osc"=>{}, "PLL"=>{}, "ATD"=> {:instances=>2},
+  #     "Comms"=>{:instances=>3, :children=>{"RAM"=>{:instances=>2}, "Osc"=>{}}}
+  #   }
+  #
+  class SubBlockParser
+    def parse(str)
+      r = {}
+      split(str).each do |tag|
+        tag, i = extract_instances(tag)
+        name, children = extract_children(tag)
+        name = camelize(name)
+        r[name] = {}
+        r[name][:instances] = i if i
+        r[name][:children] = children if children
+      end
+      r
+    end
+
+    private
+
+    # Splits the given string by comma, but understands that nested
+    # commas should not be split on
+    def split(str)
+      r = []
+      str = StringScanner.new(str)
+      r << next_tag(str) until str.eos?
+      r
+    end
+
+    def next_tag(str)
+      v = str.scan_until(/,|\[|$/)
+      if v[-1] == ','
+        v.chop.strip
+      elsif v[-1] == '['
+        open = 1
+        while open > 0
+          v += str.scan_until(/\[|\]/)
+          if v[-1] == '['
+            open += 1
+          else
+            open -= 1
+          end
+        end
+        v += next_tag(str)
+      # End of line
+      else
+        v.strip
+      end
+    end
+
+    def extract_children(tag)
+      # http://rubular.com/r/plGILY2e2U
+      if tag.strip =~ /([^\[]*)\[(.*)\]/
+        [Regexp.last_match(1), parse(Regexp.last_match(2))]
+      else
+        [tag.strip, nil]
+      end
+    end
+
+    def extract_instances(tag)
+      if tag.strip =~ /(.*)\((\d+)\)$/
+        [Regexp.last_match(1), Regexp.last_match(2).to_i]
+      else
+        [tag.strip, nil]
+      end
+    end
+
+    def camelize(val)
+      val.strip.gsub(/\s+/, '_').camelize
+    end
+  end
+end