Getting Started with Origen

Company Customization

A mechanism is provided to customize the Origen installation to a particular company.

The main customization options that this currently provides are:

• An internal gem server. This can be used to distribute private Origen plugins within your company. When this is defined any new Origen applications that are created will automatically come configured to read from your server in addition to rubygems.org.
• Integration with your company’s email delivery system, allowing your applications to easily send transactional email to their users.
• Integration with your company’s LDAP user authentication system. This API may not be generic enough yet, but it is used within NXP and we are keen to work with anyone who wants to pilot it within another company.

Whenever an application is invoked, one of the first things that Origen will do is search for a company configuration file called origen_site_config.yml.

Starting from the application directory, the file system will be checked for the presence of any valid configuration files within the application’s config or root directories, and then in any of its parent directories until it hits the file system root directory.

It will then check for a configuration file within the directory where Ruby is installed, and then again recursively through any of its parent directories.

If multiple files are found then they will all be applied, with highest priority given to the files that are found first - i.e. those located closest to the current application.

So for example, if everyone in your company uses a common Ruby installation, then you can put a config file somewhere in Ruby’s directory and it will be globally applied.

Alternatively, if all of your users have their workspaces underneath /proj or similar, then /proj/origen_site_config.yml may be a good place to put it. This also provides a mechanism for per-project or even per-application overrides by adding additional config files higher up the tree.

To create a config file simple copy the default configuration from Origen core and edit it as required.

The values present in this default file are the ones that will be applied by default in an installation where no custom configs are present.

Origen supports a static origen_site_config.yml, but also supports a template origen_site_config.yml.erb. If Origen encounters a site config with the extension .yml.erb, it will invoke the ERB template, adding some dynamic nature to the configuration. With this, the same configuration file can be used throughout but can set the site according to the current operating system, the hostname, or anything else. If you are not familiar with ERB templating, you can view a quickstart guide on the Origen docs.

The site config will automatically include Origen’s Boot API, and can be used freely out of the gate.

Command Line Driven

Origen provides a site command to assist with retrieving and tracing site config variables. This command has the following sub-commands:

• env [filters...] Shows the current site config variables. Analogous to ‘env’. Various filters can be given to filter the output (similar to piping the output to grep).
• configs Shows the current config files and their indexes along the site config load chain.
• inspect_config [config_indexes...] Inspects the configuration(s) at the provided indexes. Indexes can be found from the above command.
• inspect_variable [variable_names...] Inspects and traces the variable(s) through the various site configs, allowing you to see what the variable was at each config index.
• refresh Refreshes the centralized site config.

When first creating and debugging the site config, these commands can be useful for tracing and checking the configuration.

Interactive

To test if your configuration values are being applied, open a console within an Origen application:

origen i

You can then query the current live values via the following API, where the method names correspond directly to the attribute names in the config file:

Origen.site_config.gem_server          # => nil
Origen.site_config.gem_manage_bundler  # => true

Origen supports a single config that, instead of being a local file along the load path, can be a URL corresponding to a raw site config. Origen will issue a HTTP request and read the contents of that URL directly, parsing it as a .yml.erb file and injecting it into the site configs as the centralized_site_config. The name of the file on the server is not important, only the URL is needed.

The centralized_site_config can be set with the variable 'centralized_site_config', or using the environment variable 'ORIGEN_CENTRALIZED_SITE_CONFIG'. Like any other site config variable, this will be overridden by subsequent configs. See How The Configuration System Works for details.

For the above to be true, the centralized site config would need to be loaded last, allowing for any local site config to override which centralized config is used. However, the centralized site config is not the highest priority. Actually, it is one of the lowest. The centralized site config is injected just after the default site configs from Origen core.

For example, consider the following Origen environment:

Ruby Install: /pkg/ruby (2.3)
  Site configs: (default from Origen)
    /pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml
    /pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml.erb
  
Run Directory: /proj/example
  Site config at:
    /proj/example/origen_site_config.yml.erb
      #=> Sets centralized site config to https://internal_server/origen/config

User Directory: /home/me/
  Site config at:
    /home/me/.origen/origen_site_config.yml

The site config load order (priority listing) from highest to lowest would be:

/home/me/.origen/origen_site_config.yml
/proj/example/origen_site_config.yml.erb
https://internal_server/origen/config
/pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml
/pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml.erb

Now, consider that you update your user site config to set the centralized site config to https://my_server/origen/my_config. The new site config ordering will be:

/home/me/.origen/origen_site_config.yml
/proj/example/origen_site_config.yml.erb
https://my_server/origen/my_config
/pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml
/pkg/ruby/2.3.0/x86_64-linux/lib/ruby/gems/2.3.0/gems/origen-0.33.3/origen_site_config.yml.erb

To check the config ordering of your environment (among other settings), use the origen site command.

Caching

Adding a centralized site config ends up launching a HTTP request every time Origen is booted. To avoid bogging down both the boot process and the server (if there are many Origen users), the centralized site config will be cached for reuse.

The cached configs are stored at ~/.origen/cache/site_config. This expands, similarly to the home_dir, to /home/--user--/.origen/cache/site_config or C:\Users\--user--\.origen\cache\site_config. However, this directory is independent of any other site config variables, unlike gem_dir for example. This directory can be moved if desired by overridding centralized_site_config_cache_dir

The site config will refresh periodically, ensuring that the cached centralized site config does not get too out of sync with the latest on the server. The default refresh time is set from Origen’s default site configs and is set to 24 (hours). Any site config, including the centralized site config, can set the refresh time using the parameter centralized_site_config_refresh.

The unit for this parameter is hours, but fractional values are allowed. For example, you can use 0.5 to refresh every 30 minutes, or 2.5 to refresh every 150 minutes.

Additionally, the refresh time can be set to 0 to always refresh the site config (never use the cached values) or set to -1 to never refresh the site config (always use the cached valued).

You can refresh your site config at any time, resetting the refresh counter, using the origen site refresh. This will force a refresh of the centralized site config from the server and reset the counter for the next refresh.

SSL Certification

In general, centralized site configs will live on a company-internal server, which may or may not force HTTPS certification. This can be problematic since internal servers rarely have SSL certificates available but the address is still safe and should be reachable. To combat this, the parameter centralized_site_config_verify_ssl can be given to a local site config to indicate that SSL certification can be safely ignored. This parameter will default to true (1), so it requires the site owner to know the reasoning in the event of SSL cerification failure and to disable it accordingly.

The Origen site config has some basic methods to dynamically get, set, and remove values.

Getting Values

Origen.site_config.get(var) 
  #=> gets the current value of a site config variable 'name'
  #=> if var doesn't exist, nil is returned

Origen.site_config.get_all(var) 
  #=> gets all values of a site config variable 'name'
  #=> returns an array of values, where the higher priority values are earlier in the array
  #=> i.e., get_all(var).first is the current value and highest priority
  #=> get_all(var).last is the lowest priority value
  #=> same as Origen.site_config.add_as_highest(var, value)
  
Origen.site_config[var]
  #=> same as Origen.site_config.get(var)

Setting Values

Origen.site_config.add_as_highest(var, value)
  #=> add a new site variable at the highest priority

Origen.site_config.add_as_lowest(var, value)
  #=> add a new site variable at the lowest priority
  #=> essentially, this sets a new default value

Origen.site_config[var] = value
  #=> same as Origen.site_config.add_as_highest(var, value)

Removing Values

remove_highest(var)
  #=> remove the highest instance of var
  #=> returns the value of the variable removed
  #=> if var doesn't exist, nil is returned

remove_all_instances(var)
  #=> remove all the instances of var
  #=> returns an array of the values, from highest priority to lowest
  #=> if var doesn't exist, the an empty array is returned

purge(var)
  #=> aliase to remove_all_instances

clear
  #=> clears the site config completely

Adding New Configuration Files

You can also add a new configuration file that is not in the default paths using the methods below:

# Adds a new site config file as the highest priority
add_site_config_as_highest(site_config_file)

# Adds a new site config file as the lowest priority
add_site_config_as_lowest(site_config_file)