Getting Started with Origen

Workspace and Dependency Management

This guide provides advice on how to create new application workspaces and how to safely update your application’s dependencies.

This advice is particularly critical when running in a corporate Linux environment where the Linux distribution is older and/or you don’t have permission to write to the system Ruby installation.

The most important takeaway from this guide is to add the origen_updater plugin to your application, this provides a command which should fix your workspace if you ever end up in a situation where the origen or bundle commands are no longer working.

Add it to your application’s Gemfile like this:

# Gemfile
source 'https://rubygems.org'

gem 'origen_updater'

Note that if your application is a plugin you should always add this to your Gemfile too, i.e. don’t put it in the .gemspec.

After adding it for the first time run:

origen -v

This will invoke the plugin and it will create a new executable in your application - bin/fix_my_workspace.

This file should be committed to your revision control system to ensure that it is always available to you in the future. It’s contents may be changed automatically from time-to-time if you upgrade to a new version of the origen_updater plugin, in which case the changes should be committed to revision control too.

To fix your workspace at any time simply run:

./bin/fix_my_workspace

Creating a new workspace means setting up an existing application within a new directory for the first time.

The most important thing to remember in this case is to always run origen -v as the first step after importing the application files from your revision control system.

Doing this ensures that Origen provides some basic configuration of Bundler which will ensure that it runs well within a restricted corporate environment.

After doing this for the first time, you can then safely run the bundle command directly if you want to.

If you forget to do this and run bundle first, then you can recover by running the fix_my_workspace command as described above.

Updating dependencies means changing the version of a given gem/plugin within your Gemfile or .gemspec.

In some cases (depending on what gems you already have installed locally), you can simply make the edit and then continue running the origen command without any problems.

If you don’t already have the gem version installed locally, you will get a Bundler error which may or may not clearly describe the problem.

The easiest way to resolve things at this point is to simply run the fix_my_workspace command as described above.

Alternatively, following this sequence will create a working environment with the new dependency in most cases:

> bundle

// If that doesn't work try this, where gem_name is the name of the gem you just updated in
// your Gemfile/.gemspec
> bundle update <gem_name>

// If that doesn't work try this, this will completely re-build your gem bundle, which will pull in the
// latest versions of all gems which satisfy the rules defined in your Gemfile
> bundle update

By default, all downloaded dependencies are placed in the home_dir, which is likely pointing to ~/.origen/gems. However, gems can be large, and bigger projects (or working on several unrelated projects) means that the gems directory can quickly swell in size. This can be problematic particularly on corporate Linux systems, which usually do not have sufficient home directories to handle the size and quantity of gems we are dealing with. There are a few ways to deal with this.

Bundler comes with its own clean-up command. Running bundle clean when inside of an application will remove all of the ‘unused’ gems currently taking up space, where ‘unused’ gems are defined as gems not currently being used by the current application. This can be a quick solution if you know that you have several old, outdated gems that will likely never be used again. The only down side being other applications will require you to reinstall gems that running bundle clean deleted.

You can see bundler’s own documentation on this feature by running bundler clean -h at your console, or be visiting the bundler docs.

Relocating Your Gems

Individually, you can control where your gems are installed by using either the site configs, or by setting an environment variable. This will build or rebuild all of your gems at that location, which is generally a project drive or somewhere else where space is less of an issue.

You can set the site config variable user_gem_dir to point to the new location that you wish your gems to be installed at. Alternatively, you can set the environment variable ORIGEN_USER_GEM_DIR to accomplish the same in a more ‘linux-like’ way. Recall from the site config page that environment variables will overrule site config variables.

Origen supports setting up Tool Repository gem builds. This is considered an advance topic, and can be difficult to implement unless you are familiar with Origen’s boot process and site configs, but it mentioned here as being an effective means for advanced users or project managers to oversee a group of user’s gem install directories. For additional details, please see the advanced topic on invoking Origen.

The previous section is an example of using the site config to manage your gems workspace. However, there’s more to the workspace than just the gems directory.

The workspace is divided into three sections:

1. The Origen Home Directory: Essentially Origen’s scratch space.
2. The User’s Installation Directory: Location where user installation customizations can be found.
3. The User Gem Directory: Location to install the gems.

The above list is a top-down listing of the sections, but we’ll actually discuss in detail from the bottom-up view. Each of the sections can be customized using the site config.

Before we get started, the variables user_gem_dir, user_install_dir, and home_dir will be evaluated as paths, meaning that there’s some magic that happens between what you type into the site config, and what actually gets used. This involves:

• The ~ means username. For example, if I’m logged in as coreyeng, the path /proj/~/my_origen becomes /proj/coreyeng/my_origen.
• The path is evaluated per Ruby’s File.expand_path. Meaning that a leading ~/ becomes /home/coreyeng or C:/users/coreyeng (or whatever your OS evaluates ~/ to).
• Not starting the path with either ~/ or / is a relative path, where the current path is prepended. For example, running from /proj/my_project and using origen/~ becomes /proj/my_project/origen/coreyeng.
• You can escape the ~ using the \ symbol.
• If the path provided already ends with the append_dot_origen or append_gems, then those will not be reapplied (append_dot_origen and append_gems will be covered in the next section).

The user gem directory indicates where the gems should be installed. Moving this directory around will change where Bundler places all of your gems.

There are three site config variables to consider. Below are those variables as well as some examples of how to use them.

Default: If no user_gem_dir is specified, the gem directory falls back to home_dir.

# By default, user_gem_dir defaults to wherever the home directory is.
# origen_site_config.yml
append_dot_origen: true # Appends .origen to the path
append_gems: true       # Appends gems to the path

# In interactive session
Origen.site_config.user_gem_dir #=> '/home/<username>/.origen/gems'

Move the user_gem_dir

# origen_site_config.yml
user_gem_dir: /proj/my_gems/
append_dot_origen: true
append_gems: true

# In interactive session
Origen.site_config.user_gem_dir #=> '/proj/my_gems/.origen/gems'

Set append_dot_origen and append_gems to false to have them removed

# origen_site_config.yml
user_gem_dir: /proj/my_gems/~
append_dot_origen: false
append_gems: false

# In interactive session
Origen.site_config.user_gem_dir #=> '/proj/my_gems/<username>'

Set append_dot_origen and append_gems to custom values to have the moved

# origen_site_config.yml
user_gem_dir: /proj/my_gems/
append_dot_origen: my_workspace
append_gems: .my_gems

# In interactive session
Origen.site_config.user_gem_dir #=> '/proj/my_gems/my_workspace/.my_gems'

To review quickly, you can move the install directory for the gems by moving </code>user_gem_dir</code>. By default, this will automatically append .origen/gems to the directory path, unless append_dot_origen and append_gems specify otherwise.

The user_install_dir indicates where the user’s customization settings are located. Right now, this only includes where the global Gemfile can be located, but site configs can also be located there. Future user customization settings will also use this directory location.

Default: If no user_install_dir is specified, the home_dir is used instead.

# Default
# origen_site_config.yml
append_dot_origen: true # Appends .origen to the path.

# In interactive session
Origen.site_config.user_install_dir #=> '/home/<username>/.origen'

Move the user_install_dir

append_dot_origen: true
user_install_dir: /proj/~/install

# In interactive session
Origen.site_config.user_install_dir #=> '/proj/<username>/install/.origen'

Disable appending .origen

# Note this also affects the user_gem_dir
append_dot_origen: false
user_install_dir: /proj/~/install

# In interactive session
Origen.site_config.user_install_dir #=> '/proj/<username>/install'
Origen.site_config.user_gem_dir #=> '/proj/<username>/install/gems'

Customize the appended directory

# Note this also affects the user_gem_dir
append_dot_origen: my_origen
user_install_dir: /proj/~/install

# In interactive session
Origen.site_config.user_install_dir #=> '/proj/<username>/install/my_origen'
Origen.site_config.user_gem_dir #=> '/proj/<username>/install/my_origen/gems'

The home_dir takes care of everything else. In general, this acts as Origen’s scratch space. For example, the LSF logs and the global session are stored in this location.

Default: if no home_dir is specified, it defaults to ~/, which will be expand to your home directory (for example, /home/coreyeng on Linux, or C:\users\coreyeng on Windows).

home_dir is also the topmost path. So, if user_install_dir and/or user_gem_dir are not defined, they default back to home_dir.

If no home_dir is specified, ~/ is used

# Default

# In interactive session
Origen.site_config.home_dir #=> '/home/<username>/.origen'
Origen.site_config.user_install_dir #=> '/home/<username>/.origen'
Origen.site_config.user_gem_dir #=> '/home/<username>/.origen/gems'

Move the home_dir

# origen_site_config.yml
home_dir: /proj/origens/~

# In interactive session
Origen.site_config.home_dir #=> '/proj/origens/<username>/.origen'
Origen.site_config.user_install_dir #=> '/proj/origens/<username>/.origen'
Origen.site_config.user_gem_dir #=> '/proj/origens/<username>/.origen/gems'

Move the home_dir and disable append_dot_origen

# origen_site_config.yml
home_dir: /proj/origens/~
append_dot_origen: false

# In interactive session
Origen.site_config.home_dir #=> '/proj/origens/<username>'
Origen.site_config.user_install_dir #=> '/proj/origens/<username>'
Origen.site_config.user_gem_dir #=> '/proj/origens/<username>/gems'

Move the home_dir and change append_dot_origen

# origen_site_config.yml
home_dir: /proj/origens/~
append_dot_origen: .my_origen

# In interactive session
Origen.site_config.home_dir #=> '/proj/origens/<username>/.my_origen'
Origen.site_config.user_install_dir #=> '/proj/origens/<username>/.my_origen'
Origen.site_config.user_gem_dir #=> '/proj/origens/<username>/.my_origen/gems'

The purpose of having all these site configs variables is to allow full customization when desired, but be able to simplify common usages. For example, if you want to move your entire .origen from your home directory to some project directory, you only need to move home_dir. Everything else will go with it. But, if you want to leave your custom user setup and be able to get all the logs and global session in your home directory but just move where all your gems are stored, you can do that too.