origen_app_generators 0.0.2

data/templates/app_generators/test_engineering/generic_test_block/target/ultraflex.rb

@@ -0,0 +1,10 @@
+# The target file is run before *every* Origen operation and is used to instantiate
+# the runtime environment - usually this means instantiating a top-level SoC or
+# IP model.
+#
+# Naming is arbitrary but instances names should be prefixed with $ which indicates a 
+# global variable in Ruby, and this is required in order for the objects instantiated
+# here to be visible throughout your application code.
+
+$dut = <%= @namespace %>::TopLevel.new   # Instantiate a DUT instance
+$tester = Testers::UltraFLEX.new

data/templates/app_generators/test_engineering/generic_test_block/target/v93k.rb

@@ -0,0 +1,10 @@
+# The target file is run before *every* Origen operation and is used to instantiate
+# the runtime environment - usually this means instantiating a top-level SoC or
+# IP model.
+#
+# Naming is arbitrary but instances names should be prefixed with $ which indicates a 
+# global variable in Ruby, and this is required in order for the objects instantiated
+# here to be visible throughout your application code.
+
+$dut = <%= @namespace %>::TopLevel.new   # Instantiate a DUT instance
+$tester = Testers::V93K.new

data/templates/web/_history.md

@@ -0,0 +1,166 @@
+<a class="anchor release_tag" name="v0_4_5"></a>
+<h1><a href="#v0_4_5">Tag: v0.4.5</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 28-May-2015 08:52AM
+
+
+Fixed generic plugin build
+
+<a class="anchor release_tag" name="v0_4_4"></a>
+<h1><a href="#v0_4_4">Tag: v0.4.4</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 21-May-2015 07:56AM
+
+
+Added pattern dir to generic test block
+
+<a class="anchor release_tag" name="v0_4_3"></a>
+<h1><a href="#v0_4_3">Tag: v0.4.3</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 20-May-2015 08:56AM
+
+
+Updates symlink handling and other patches to fix new app creation on Windows.
+
+<a class="anchor release_tag" name="v0_4_2"></a>
+<h1><a href="#v0_4_2">Tag: v0.4.2</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 23-Apr-2015 09:50AM
+
+
+Added Testers plugin and basic test program setup to the generic test block template
+
+<a class="anchor release_tag" name="v0_4_1"></a>
+<h1><a href="#v0_4_1">Tag: v0.4.1</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 31-Mar-2015 04:12AM
+
+
+Removed the code coverage boiler plate code in the generated config/commands.rb file, Origen
+core now provides this and new apps don't need it.
+
+<a class="anchor release_tag" name="v0_4_0"></a>
+<h1><a href="#v0_4_0">Tag: v0.4.0</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Ronald Lajaunie on 08-Mar-2015 20:19PM
+
+
+Added MPG Test Block plugin template.
+
+<a class="anchor release_tag" name="v0_4_0_pre0"></a>
+<h2><a href="#v0_4_0_pre0">Tag: v0.4.0.pre0</a></h2>
+
+##### Branch: 'Trunk'
+
+##### by Corey Engelken on 24-Feb-2015 13:32PM
+
+
+Added first version of the MPG BOM Application generator.
+
+<a class="anchor release_tag" name="v0_3_5"></a>
+<h1><a href="#v0_3_5">Tag: v0.3.5</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 19-Feb-2015 05:33AM
+
+
+Added debugger gems to Gemfile templates
+
+<a class="anchor release_tag" name="v0_3_4"></a>
+<h1><a href="#v0_3_4">Tag: v0.3.4</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 15-Jan-2015 05:51AM
+
+
+All plugins now come with a templates/shared directory
+
+<a class="anchor release_tag" name="v0_3_3"></a>
+<h1><a href="#v0_3_3">Tag: v0.3.3</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 15-Jan-2015 04:57AM
+
+
+Patch to all plugin generators to require config/application.rb from the main plugin
+require file (lib/plugin\_name.rb).
+This is required for Origen to identify that the given gem is an Origen plugin, it is not
+required for top-level applications where Origen will automatically load
+config/application.rb
+
+<a class="anchor release_tag" name="v0_3_2"></a>
+<h1><a href="#v0_3_2">Tag: v0.3.2</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 15-Jan-2015 03:27AM
+
+
+Fixed the generated wild card require code in lib/app\_name.rb to work correctly in the
+case of a plugin being used by another app.
+
+<a class="anchor release_tag" name="v0_3_1"></a>
+<h1><a href="#v0_3_1">Tag: v0.3.1</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 09-Jan-2015 05:11AM
+
+
+New apps will now start from version 0.1.0, this is to avoid Bundler issues with
+pre-release
+tags of 0.0.0.
+
+Updated the plugin web template to give a better install instruction.
+
+<a class="anchor release_tag" name="v0_3_0"></a>
+<h1><a href="#v0_3_0">Tag: v0.3.0</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 11-Dec-2014 06:57AM
+
+
+Added a generator and rake task (rake new) to create a new generator within this application and
+documentation on how to create a new generator.
+
+The generator selection process now supports domain specific generators.
+
+Added a generic test block generator as an initial example of a domain specific generator.
+
+<a class="anchor release_tag" name="v0_2_0"></a>
+<h1><a href="#v0_2_0">Tag: v0.2.0</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 08-Dec-2014 10:55AM
+
+
+Added initial 2.5.0 compatible plugin shell
+
+<a class="anchor release_tag" name="v0_1_0"></a>
+<h1><a href="#v0_1_0">Tag: v0.1.0</a></h1>
+
+##### Branch: 'Trunk'
+
+##### by Stephen McGinty on 05-Dec-2014 11:21AM
+
+
+Initial release with a working generic application builder
+
+

data/templates/web/archive.md.erb

@@ -0,0 +1,11 @@
+% render "layouts/basic.html", tab: :archive, yammer_comments: false do
+
+# Archive
+
+Documentation from previous releases is available via the links below:
+
+% Origen.app.versions.reverse_each do |version|
+* [<%= version %>](<%= Origen.app.config.web_domain %>/<%= version.gsub(".", "_") %>)
+% end
+
+% end

data/templates/web/contact.md.erb

@@ -0,0 +1,36 @@
+% render "layouts/basic.html", tab: :contact, yammer_comments: false do
+
+# Contact Us
+
+The following engineers can be contacted about this application:
+
+% Origen.app.developers.each do |user|
+* [<%= user.name %>](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl\<%= user.r_number %>) 
+% end
+
+%# An example of how to write a contact page:
+%#Please use PDM For any bug reports or change/feature requests:
+%#
+%#* [C90TFS_NVM_tester on PDM](http://designpdm.freescale.net/Agile/PLMServlet?fromPCClient=true&module=PartFamilyHandler&requestUrl=module%3DPartFamilyHandler%26opcode%3DdisplayObject%26classid%3D2000004409%26objid%3D17718323%26tabid%3D2%26)
+%#
+%#For test related issues you can contact:
+%#
+%#* [Stephen McGinty](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl\r49409) 
+%#* [Thao Huynh](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl%5CR6AANF) 
+%#
+%#For product/yield issues contact:
+%#
+%#* [Andrew Hardell](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl%5CR12635)
+%#* [Eddie Lepore](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl%5CB06626)
+%#
+%#The manager of this project is:
+%#
+%#* [Wendy Malloch](http://freeshare.freescale.net:2222/my/Person.aspx?accountname=fsl%5CTTZ231)
+%#
+%#
+%#Finally if you are not sure who to contact, or if your question may have device/reliability
+%#implications, then you can use the Split Gate Flash Test and Reliability mailing list:
+%#
+%#* [Email SGFTANDR](mailto:SGFTANDR@freescale.com)
+
+% end

data/templates/web/docs/developers/creating.md.erb

@@ -0,0 +1,290 @@
+% render "../../layouts/doc.html" do
+
+This document outlines the process for creating a new application generator.
+
+### Background
+
+This plugin uses a code generator API from Origen core which itself leans heavily on a 3rd party gem library called
+Thor. This gem is used quite widely in the Ruby community for this kind of thing, not least by the code generators
+provided by the Ruby on Rails platform.
+
+The code generator API allows the user to do things like:
+
+* Run code to collect user input
+* Compile templates to produce dynamic output based on the user's responses
+* Copy files verbatim
+* Create directories and symlinks
+* Delete and inject lines into existing files
+
+Each application type that can be generated by this plugin is an example of a code generator.
+
+The code new application generators are organized into the following hierarchy:
+
+~~~text
+OrigenAppGenerators::Base
+  |
+   -> OrigenAppGenerators::Application
+        |
+         -> OrigenAppGenerators::Plugin
+~~~
+
+**All additional generators within this application must be a subclass of either <code>OrigenAppGenerators::Application</code>
+or <code>OrigenAppGenerators::Plugin</code> depending on whether the end application is intended to be a plugin or not.**
+
+The new application generators should all perform the following functions:
+
+* Prompt the user with some questions to get the new application name and so on
+* Create the new application files by either copying or compiling source files and creating
+  symlinks or directories as required
+* Make any final modifications to the resulting files
+* Display any information that the user should know about their new application
+
+#### Generator Execution
+
+When a generator is executed any methods defined in it will be called in the order that they are
+defined.
+Any methods that are marked as <code>protected</code> will not be called.
+
+For example when the following generator is executed:
+
+~~~ruby
+module OrigenAppGenerators
+  class MyAppGenerator < Application
+    def say_hello
+      puts "Hello" 
+    end
+
+    def call_a_helper
+      puts "About to call"
+      a_helper_method
+      puts "Returned from call"
+    end
+
+    protected
+
+    def a_helper_method
+      puts "Helper method called!"
+    end
+
+    def this_does_nothing
+      puts "Another method called!"
+    end
+  end
+end
+~~~
+
+Then you would see this:
+
+~~~text
+Hello
+About to call
+Helper method called!
+Returned from call
+~~~
+
+Note that any methods defined by the parent class will get called first. In this application the
+parent <code>Application</code> and <code>Plugin</code> classes implement a method to get the user
+input that will be common to all applications.
+
+You can disable this behavior if required by re-defining the relevant methods within the child generator class.
+
+#### Source Files
+
+All template or static source files for the generators live in <code>templates/app_generators/</code> and from
+there in sub folders based on the name of the particular generator.
+
+All path references to source files made in your generator should be relative to its source file folder, and in
+practice what this means is that if you want to refer to the source file of what will become
+<code>Origen.root/config/application.rb</code> then you just refer to <code>config/application.rb</code>.
+
+When looking for a particular source file the generator will search in the various source directories
+belonging to your generator's parent classes.
+For example let's say you make a test engineering generator that has the following class hierarchy:
+
+~~~text
+OrigenAppGenerators::Base
+  |
+   -> OrigenAppGenerators::Application
+        |
+         -> OrigenAppGenerators::Plugin
+              |
+               -> OrigenAppGenerators::TestEngineering::TestBlock
+~~~
+
+Then the following source paths will be searched in this order:
+
+~~~text
+templates/app_generators/test_engineering/test_block
+templates/app_generators/plugin
+templates/app_generators/application
+~~~
+
+This means that if you create a file called <code>config/application.rb</code> within
+<code>templates/app_generators/test_engineering/test_block</code> then this will override the corresponding
+file from the plugin sources and which would itself override the same file from the application sources.
+
+However see the warning in [The Filelist](<%= path "docs/developers/creating#The_Filelist" %>) section below before doing this!
+
+### Creating a New Generator
+
+A rake task is provided to create a new generator, run it as follows:
+
+~~~text
+rake new
+~~~
+
+### Lean Environment
+
+When the generator is run by a user to generate a new application, it will not run within the scope of an
+Origen application.
+This means that any references to <code>Origen.app</code> within the generator code are meaningless and will
+result in an error.
+
+Furthermore because there is no application there is also no associated gem bundle, so the generator must
+be able to run within the lean Ruby environment that is used to boot Origen. In practice what this means is
+that you can use any gems that Origen itself relies on (these will be installed in the base Ruby installation),
+but you cannot use any others.
+
+The rake tasks provided for testing your new generator will run it within the lean environment, so if it
+works there you can be confident that it will also run in production.
+
+### The Filelist
+
+Each generator should return the list of files to be created in the new application via its
+<code>filelist</code> method.
+If you don't make any changes to this then it will simply inherit the list of files defined
+by the generator's parent class.
+
+The filelist is also used to define any directories or symlinks that should be created.
+The generator class created by the <code>rake new</code> task contains a commented example of how to add or
+remove the various elements from the filelist.
+
+Some application generators may not make any changes to the filelist and will simply augment
+the basic application/plugin shell by adding additional code to some of the existing files.
+
+This can be done by either overriding the source file by defining it in the generator's own
+source directory, or by [post-modifying](<%= path "docs/developers/creating#Post_Generation_Modifications" %>)
+the files after the filelist has been rendered.
+
+<div class="alert">
+  <strong>Warning!</strong> While it is tempting (and easier) to simply copy a source file and then
+  edit it as required for your target application, this will make your generator harder to maintain as it
+  will not automatically pick up changes and improvements to the master templates that will occur over time.
+  Therefore it is always preferable to post-modify the file to delete sections or to modify or add additional code
+  whenever possible.
+</div>
+
+**Note that developers should not add logic to the application/plugin master source files to
+implement generator specific output. This approach is not scalable as in the future this plugin
+is expected to support many different application types.**
+
+Instead individual generators must either completely override or post-modify the master files
+as appropriate.
+
+#### Templates
+
+All files in the file list will be compiled unless explicitly marked with <code>copy: true</code>
+or if the destination file name ends in <code>.erb</code>.
+
+ERB markup can be used the same way as in regular Origen templates with the following exceptions:
+
+Whole line Ruby is not enabled (a limitation imposed by Thor), therefore instead of this:
+
+~~~eruby 
+<%= "%" %> if x_is_true
+Include something
+<%= "%" %> end
+~~~
+
+You must do:
+
+~~~eruby 
+<%= "<" + "% if x_is_true -%" + ">" %>
+Include something
+<%= "<" + "% end -%" + ">" %>
+~~~
+
+Access to variables collected by your generator at runtime is done by assigning them to instance
+variables (instead of the options hash used by the Origen compiler).
+
+So for example if you have your user input a product name, then you should assign that to an
+instance variable:
+
+~~~ruby
+@product_name = get_product_name
+~~~
+
+Then in the template:
+
+~~~eruby
+The product name is <%= "<" + "%= @product_name %" + ">" %>
+~~~
+
+By convention templates in this plugin do not end in <code>.erb</code> and this is reserved
+for files that would become <code>.erb</code> files in the end application.
+
+### Post Generation Modifications
+
+It is better to customize any files that are common to all applications
+by post modification rather than by completely overriding the entire file.
+
+To do this you have access to the Thor Action methods described here:
+[Thor Action API](http://www.rubydoc.info/github/wycats/thor/Thor/Actions)
+
+You can see some examples of these being used in the <code>enable</code> method in
+<code>lib/app_generators/new.rb</code> where they are used to add the new generator details
+to <code>lib/origen_app_generators.rb</code>.
+
+As a quick example say you wanted to add a method to <code>config/application.rb</code>, this
+could be achieved by injecting it at the end of the class like this:
+
+~~~ruby
+# Always ensure the filelist has been rendered first
+def generate_files
+  build_filelist 
+end
+
+# Add a custom domain method to config/application.rb
+def add_method_to_application
+  # Define a regular expression to define a point in the file where you want to inject, in this
+  # case the 'end' of the class definition (the only 'end' that occurs at the beginning of a line)
+  end_of_class = /^end/
+  # Define the code snippet
+  code = <<-END
+  def some_domain_specific_method
+    do_something
+  end  
+END
+  # Now inject it
+  inject_into_file "config/application.rb", code, before: end_of_class
+end
+~~~
+
+### Documentation
+
+The rake task will create a documentation file for your new generator in
+<code>templates/web/origen_app_generators/</code> and this should be used to document
+any information about the new application shell that your target audience might find useful. 
+
+This page will be automatically linked to from the [OrigenAppGenerators Homepage](<%= path "/" %>)
+when it is next released.
+
+### Testing the Generator
+
+Rake tasks are provided to test your new generator, to run the <code>origen new</code> command as
+it would appear to your audience run <code>rake test</code>.
+
+Alternatively to skip the first section that selects the required generator you can run
+<code>rake 'run[TestEngineering::TestBlock]'</code>, substituting the class name for that of
+your new generator.
+
+In both cases the new application will be built in <code>tmp/</code> and you can cd into
+that and run it to see if everything works.
+
+### Releasing the Generator
+
+To release the generator simply release a new production version of this plugin, the
+<code>origen new</code> command will automatically check for and run the latest production version
+of it every time it is invoked.
+
+% end

data/templates/web/docs/environment/installation.md.erb

@@ -0,0 +1,12 @@
+% render "layouts/doc.html" do
+
+Execute the following commands to create a development workspace:
+
+~~~
+mkdir <%= Origen.app.name %>
+cd <%= Origen.app.name %>
+dssc setvault <%= Origen.config.vault %> .
+dssc pop -rec -uni -force -get -ver <%= Origen.app.version %> .
+~~~
+
+% end

data/templates/web/docs/environment/introduction.md.erb

@@ -0,0 +1,10 @@
+% render "layouts/doc.html" do
+
+This documentation is primarily aimed at engineers who want to either create a new shell generator
+or to maintain or modify an existing one.
+
+All of the user facing documentation is contained on the [Home page](<%= path "/" %>) and
+which includes links to any shell specific information that has been provided by the
+shell authors.
+
+% end

data/templates/web/example.md.erb

@@ -0,0 +1,73 @@
+% render "layouts/basic.html" do
+
+%# HTML tags can be embedded in mark down files if you want to do specific custom
+%# formatting like this, but in most cases that is not required.
+<h1><%= Origen.config.name %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>
+
+Welcome to your application's documentation...
+
+Here are some pointers to get you started with writing Origen documents:
+
+### Markdown
+
+Most of your documents (such as this one you are reading) will be written in Markdown. This
+allows you to create good looking and well formatted web-based documents easily and without
+having to know anything about HTML.
+
+Origen uses the Kramdown library to process the Markdown, this has a good quick reference
+guide on the Markdown syntax here: [Markdown Quick Reference](http://kramdown.rubyforge.org/quickref.html)
+
+### Links
+
+Links can be added to your documents easily, like this one for example:
+
+* [Freescale](http://www.freescale.com)
+
+For linking to other pages within your own documents it is recommended that you use the
+'path' helper to generate the url. By doing this Origen should generate links that work
+correctly for both serving documents locally when developing and when deploying to a remote
+web server. Here is an example:
+
+* [Docs](<%= path "/docs/environment/introduction" %>)
+
+### Code Examples
+
+In the course of writing documentation you will probably want to show code examples
+from time to time. Generic code snippets can be easily formatted with a mono-spaced
+font like this:
+
+~~~
+origen t debug
+origen g list/production.list
+~~~
+
+If you are showing examples of Ruby then they can be easily syntax-highlighted for
+better presentation:
+
+~~~ruby
+# Cool, this is easy
+def some_ruby
+  @blah = Blah.new
+end
+~~~
+
+Origen uses the Coderay library for syntax highlighting and therefore should in theory
+be able to highlight all languages listed here: [CodeRay Syntax Highlighting](http://coderay.rubychan.de/)
+
+### Custom HTML
+
+You may occasionally wish to have low level control of your documentation's HTML, this
+can be done by simply embedding the HTML directly alongside the Markdown.
+
+Origen already uses the [Twitter Bootstrap](http://twitter.github.io/bootstrap/index.html)
+framework to generate these documents, so you already have full access to the features
+provided by that framework.
+
+For example here is how to insert a [Bootstrap alert](http://twitter.github.io/bootstrap/components.html#alerts):
+
+<div class="alert">
+  <button type="button" class="close" data-dismiss="alert">&times;</button>
+  <strong>Warning!</strong> This example was just copied directly from the bootstrap documentation!
+</div>
+
+% end

data/templates/web/index.md.erb

@@ -0,0 +1,48 @@
+% render "layouts/basic.html" do
+
+%# HTML tags can be embedded in mark down files if you want to do specific custom
+%# formatting like this, but in most cases that is not required.
+<h1><%= Origen.app.namespace %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>
+
+### Introduction
+
+This plugin is used by Origen Core to generate new application shells via the <code>origen new</code>
+command.
+
+As well as providing generic plugin and application shells many customized builds for a particular
+engineering domain, function, or business group are available to.
+
+### How to Use
+
+Run the <code>origen new</code> command outside of an application workspace, this will automatically
+run the latest production release of this plugin to generate the new application:
+
+~~~text
+origen new my_app_name
+~~~
+
+If you want to use a pre-release or older version of the generator a version can be specified
+like this:
+
+~~~text
+origen new my_app_name --version 0.1.0
+~~~
+
+### Available Application Shells
+
+The following application shells are currently available, click the links to see any specific
+information that the shell author has provided:
+
+* [Generic Application](<%= path "origen_app_generators/application" %>)
+* [Generic Plugin](<%= path "origen_app_generators/plugin" %>)
+
+%   OrigenAppGenerators::AVAILABLE.reverse_each do |domain, generators|
+#### <%= domain %>
+
+%     generators.reverse_each do |generator|
+* [<%= generator.desc %>](<%= path generator.to_s.underscore %>)
+%     end
+
+%   end
+
+% end