Getting Started with Origen
Application Directory Structure
All Origen applications have the same directory structure which is setup when a new application
is created by running the
origen new my_app command.
This guide provides an overview of what each directory is used for.
app/directory were spread out between various top-level directories and often in a less structured way. While the old directories are still supported by Origen, all new applications should conform to the newer structure described here.
Here is the top-level directory structure of a typical Origen application:
. ├── app/ ├── config/ ├── doc/ ├── environment/ ├── lbin/ ├── log/ ├── output/ ├── spec/ ├── target/ ├── tmp/ ├── Gemfile ├── Gemfile.lock ├── Rakefile └── README.md
Here is a description of each component:
This is where the bulk of your application resides and it is covered in more detail below.
You should think of the
app/ directory as being your application, while the rest of the directories and files
at the top-level are mainly concerned with collecting output, managing your application’s runtime environment,
and hooking it into the Origen eco-system.
This directory is for configuring Origen to your application’s needs and it provides the hook points to add things like additional application-specific Origen commands. It contains a number of standard files and these are discussed in more detail below.
This directory is only used by Origen to store your application’s release note history whenever you tag/release your app through Origen. You can also use it as a place to store any documentation associated with your application.
Environments refer to the runtime environment that is being targeted by whatever your Origen application is creating. For example, in a test engineering application an environment would exist for each ATE platform you support. A simulator is another common Origen environment. A file should exist in this directory for each target environment that your application supports.
See here for more information on creating and setting environments - Runtime Environment.
To create a simulation environment, see here - Simulation Environment Setup.
This contains bin stubs which are executables that ensure that the given tool is invoked within
your application’s gem bundle.
You should check this directory into your revision control system and you should add
./lbin to your
PATH, meaning that whenever you are running
origen from your application workspace, you are really
All Origen log files will be created in here.
This is the default Origen output directory, though the location of this is something that you can configure
within your applications’
If your create unit tests for your application (meaning tests of the app itself) then they would go in here.
Similar to the
environment/ directory, but concerned with specifying what silicon is being targeted by whatever
your Origen application is creating.
See here for more information on creating and setting targets - Runtime Target.
Origen and plugins will store temporary data in here, it should not be added to your revision control system and it can be safely deleted at any time.
This specifies your application’s dependencies, see Understanding Gems for more information.
This is a generated file that should be checked into your revision control system as part of your application.
Gemfiles are often setup such that some dependencies do not have a hard version specified and therefore a range of
versions could satisfy the requirements.
However, when working as a team it is preferable to know that everyone is working with the same execution environment.
This file records the dependency versions that were actually used the last time the gem bundle was created (the last time
the Gemfile was changed), and all users that have the same
Gemfile.lock in their workspace are guaranteed to be running the
same execution environment.
Rake is the Ruby equivalent of the Unix program Make, if you are familiar with it, this is the Ruby equivalent of
In practice, this is not used much within the Origen ecosystem and generally application-specific Origen commands
and plugin commands are preferred instead.
However, if you want to use Rake within your application then this file is already setup to load Origen.
A good place to provide an introduction to your application for other developers.
app/ directory typically contains the following sub-structure:
. ├── app/ ├── blocks/ ├── flows/ ├── lib/ │ ├── my_app_name/ │ └── my_app_name.rb ├── patterns/ └── templates/ └── web/
Here is a description of each item:
A block contains all of the Origen infrastructure to model and control a specific piece of silicon. Blocks can instantiate other blocks as sub-blocks, and therefore it is common to have a block that represents the top-level device, and then other blocks to represent the individual IPs that it contains.
All test program flow files should be stored in here.
This is where to create any Ruby files that do not otherwise fall into one of the other standard directories.
This directory is added to Ruby’s global load path, which means that files within it can be loaded from anywhere
with a relative path, e.g.
However, this directory also supports auto-loading which means that
you should never have to manually load the files in here as long as you follow the
auto-loading naming conventions.
app/lib/<my_app_name>.rb is automatically loaded whenever your application boots and it is therefore a convenient place to
do any loading of any external libraries that your application depends on.
Since this directory is in Ruby’s global load path, it is very important that all code you put in here is wrapped in your application’s namespace to avoid naming collisions, like this:
module MyAppName # Your code here end
and then placed within the
my_app_name sub-directory to reflect that it lives within that namespace.
All test pattern source files should be stored in here.
All compiler template files should be stored in here.
The templates concerned with creating your application’s online documentation should be stored in the
config/ directory typically contains the following files:
. ├── config/ ├── application.rb ├── boot.rb ├── commands.rb ├── maillist_dev.txt ├── maillist_prod.txt └── version.rb
Here is a description of each of them:
Specifies global configuration for your application, for example to configure its source code repository, its web site url, or to setup the output directory and other attributes of Origen’s various generators.
This file is also defining an object that represents your application, this is automatically instantiated by
Origen and is accessible via
Origen.app. The application configuration is therefore accessible via
Origen.app.config and also
Origen.config for short.
See the plugin guide for more information on accessing the application
objects of plugins.
This application object is also commonly used to implement callback handlers and other globally accessible methods that are specific to your application.
This file is used by Origen to boot your application, i.e. it is the first thing that Origen will load whenever
your application is invoked.
By default, it simply requires the top-level lib file
app/lib/<my_app_name>.rb and that is the file that you
would normally modify to load additional application dependencies rather than the boot file.
In that case, what it the boot file for?
It fact, it is only relevant if your application is an Origen plugin and in that case there is a distinction between the application booting within its own workspace and when being boot as a dependency of another application. See the guide on Creating a Plugin for more information on this.
This file can be used to register and implement application-specific Origen commands to support your application.
See the dedicated guide on Adding Commands for more information.
This defines a list of email addresses that should be informed whenever there is any release of your application, including development releases.
See the guide on Users, Emails and Maillists for more information.
Similar to the development mailing list, this list of emails will only be notified whenever there is a production release of your application.
Note that there is no need to duplicate the development emails in this file, this is only the additional list of users that should be notified if the release is intended for production use.
This file defines your application version, it is automatically updated by Origen whenever your application
is released via the
origen rc tag command.