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
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:
This will invoke the plugin and it will create a new executable in your
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:
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
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
directly if you want to.
If you forget to do this and run
bundle first, then you can recover by running
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
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
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.
home_dir. These items are small, and should not fill up even a minimal, corporate Linux home directory. For details on moving this as well, please see the advanced topic here.
lbindirectories to see this take effect. These store links and configuration settings to your original gems directory. Don't worry though, Origen will rebuid them for you, with the updated gem directory this time.
ORIGEN_GEM_INSTALL_DIRare still valid. However, these fulfill the same purpose as
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
The workspace is divided into three sections:
- The Origen Home Directory: Essentially Origen’s scratch space.
- The User’s Installation Directory: Location where user installation customizations can be found.
- 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
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:
username. For example, if I’m logged in as
coreyeng, the path
- The path is evaluated per Ruby’s File.expand_path.
Meaning that a leading
C:/users/coreyeng(or whatever your OS evaluates
- Not starting the path with either
/is a relative path, where the current path is prepended. For example, running from
- You can escape the
- If the path provided already ends with the
append_gems, then those will not be reapplied (
append_gemswill be covered in the next section).
user gem directory indicates where the gems should be installed. Moving this directory around will
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
# 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_gems specify otherwise.
ORIGEN_GEM_INSTALL_DIRare still valid. However, these fulfill the same purpose as
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'
home_dir takes care of everything else. In general, this acts as Origen’s scratch space. For example,
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
home_dir is also the topmost path. So, if
are not defined, they default back to
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.