From Nocturnal.insomniacgames.com

Contents 1 Overview 2 Download 3 Configuration 3.1 Command Line Options 3.1.1 -code 3.1.2 -assets 3.1.3 -config 3.1.4 -build/-mode 3.1.5 -shell 3.1.6 -run 3.1.7 -exec 3.1.8 -stderr2stdout 3.1.9 -help/-usage 3.2 ProjectSettings.xml 3.3 UserSettings.xml 3.4 Project Settings 3.4.1 Project Name 3.4.2 Directories 3.5 Path Settings 3.6 Perl Settings 3.7 Environment Variables 3.8 Programmatic Substitutions

Overview

The Environment Shell allows for users to easily work in a variety of projects and configurations. Common examples include programmers working in various code branches in different build modes (debug vs. release) and users working in different asset branches.

Download

http://nocturnal.insomniacgames.com/releases/EShell

Configuration

Command Line Options

-code

Sets the code context relative to the project code directory.

-assets

Sets the assets context relative to the project assets directory.

-config

Specifies the config to use from the ProjectSettings/UserSettings files.

-build/-mode

Sets the build mode to use. (Eg: release)

-shell

Specifies the shell to use, which defaults to cmd.exe.

-run

Specifies a command to run, hiding the shell process window that spawned it. This is useful for launching graphical programs (such as IDEs, etc.) with appropriate environment settings but without having the console owning the process appear.

-exec

Specifies a command to execute when the shell starts up.

-stderr2stdout

Redirects stderr to stdout. This is sometimes useful for capturing output in automated processes.

-help/-usage

Displays program usage.

ProjectSettings.xml

Under the config/ directory in a given project, there should be a ProjectSettings.xml file. This file specifies a variety of settings in a simple XML format.

UserSettings.xml

The environment shell will look for a UserSettings.xml file in the config/ directory, parallel to the ProjectSettings.xml file. If this file is found, its settings are read and will augment and/or override those specified in ProjectSettings.xml.

If a setting is only specified in UserSettings.xml, it will augment the settings specified in ProjectSettings.xml. If a setting is specified in both the ProjectSettings.xml and UserSettings.xml file, the value in the UserSettings.xml file will take precedence.

Note that XML is a heirarchical data format. You must place entries in your UserSettings.xml at the same point in the heirarchy if you wish them to work properly. Ie:

 <ProjectSettings>
   <Blah>
     <Foo>yak</Foo>
   </Blah>
 </ProjectSettings>

'Foo' would be overridden (set to 'bar' rather than 'yak') by the following UserSettings.xml file:

 <UserSettings>
   <Blah>
     <Foo>bar</Foo>
   </Blah>
 </UserSettings>

Project Settings

Project Name

The project name should be specified using the 'Name' tag:

 <Name>TheProject</Name>

Directories

Certain project-wide directory settings are supported:

• CodeDirectory - where code branches will live
• AssetDirectory - where asset branches will live
• ToolsDirectory - where tools will live

Each of these should be set to the project-root-relative directory of your choice.

 <DirectorySettings>
   <CodeDirectory>code</CodeDirectory>
   <AssetDirectory>assets</AssetDirectory>
   <ToolsDirectory>tools</ToolsDirectory>
 </DirectorySettings>

Path Settings

The 'PathSettings' section of the config file specifies information about paths to binaries. It consists of a set of 'PathDir' elements that will be added to the path. Paths are relative to the project directory, or can be specified in absolute form.

Eg:

 <PathSettings>
   <PathDir>x:\blah\yak\foo</PathDir> ( adds the absolute path x:\blah\yak\foo to the user's path )
   <PathDir>\yak\foo\whale</PathDir>  ( adds the absolute path x:\yak\foo\whale to the user's path,
                                        assuming we're on the X: drive )
   <PathDir>blah\foo</PathDir>        ( adds the absolute path x:\[project path]\blah\foo to the user's
                                        path, where [project path] is determined by finding the directory
                                        that contains 'config\ProjectSettings.xml' )
   ( You can also specify the 'append' order to entries.  By default, paths will be added *before*
     the system-wide paths.  Using the 'append' order will cause a path to be appended *after* system-wide
     paths. )
   <PathDir order="append">c:\Program Files\Alias\Maya8.0\bin</PathDir>
 </PathSettings>

Perl Settings

The 'PerlSettings' section specifies the paths to be added to perl's 'site-lib' using the 'LibDir' tag.

Eg:

 <PerlSettings>
   <LibDir>sdk\Insomniac\Perl\0.0.10\site-lib</LibDir>
   <LibDir>tools\perl</LibDir>
 </PerlSettings>

Environment Variables

Environment variables can be set using this section of the config file. It consists of a set of 'EnvVar' elements.

Eg:

 <EnvironmentVariables>
   <EnvVar variableName="PERL_SIGNALS" value="unsafe" />
 </EnvironmentVariables>

Programmatic Substitutions

Using the string '[[<variable name>]]' in a setting in the environment shell configuration will cause that string to be replaced with the value of the variable with that name at the time of processing within the script. Useful variables are:

• projectRootDirectory
• codeDirectory
• assetDirectory
• toolsDirectory
• codeBranchDirectory
• codeBranchName
• assetBranchDirectory
• assetBranchName