Userdata Directory

« Notes about included models | EDGE User’s Guide | Running standalone »

The Problem

When receiving a delivery of EDGE, user's will need to customize various things for their facility or simulation including config file options, gui scripts, overlays, interface code, models, etc. This means there will be file changes and additions in a variety of locations.

Unfortunately, whenever trying to upgrade to a new release, this meant that all of the integration had to be done again inside the new release.

The Solution

The userdata directory is an attempt to remedy this problem. The idea is that ALL user customizations should take place within the userdata directory. Effectively, all other directories in the release could be considered read-only. If all works out, theoretically an update to another release would simply consist of untarring the new release, and copying over or pointing to the "userdata" directory with the previous one.

Since this is the first cut at this feature, it is expected that there will be times when customization requires the editing of a delivered file outside of the "userdata" directory. Please let us know if you find such a situation so we can add the necessary hooks in future releases so this is not required.

More info

The included directory called "userdata" is really intented to be a template. In most cases, we recommend the user copy this directory to one that contains their project name. For example, you may have 5 userdata.xxx directories for 5 different projects: userdata.project1, userdata.project2, and so on. Then, before running, the user would select which project they wish to run with via the $USERDATA environment variable. In csh, this would be:

setenv USERDATA userdata.projectX
./run_graphics

If you get an error saying $HOST is not defined, see this issue: Issues.00650

That way, many projects can have their settings stored separately, with an easy mechanism to choose which one to run with.

At the top level, the userdata directory includes "user.cfg" and "user_env.csh". These two files are the top-level hooks for users to add all of their customizations, including loading of their own config files, plugins, gui elements, scripts, overlays, models, etc. It can also be used for new display context definitions to integrate into a facility or customize the look and feel.

The "$USERDATA/user.cfg" file is meant as a starting skeleton for config file customization. It is set up by default to postload "$USERDATA/configs/user_models.cfg" where users can add data nodes, model nodes, cameras, etc. Also, the DEFINES block is the appropriate place to override environment variables that are used with EDGE.

The "$USERDATA/user_env.csh" file is sourced at the bottom of the edge_env file if it exists. This lets the user overwrite any environment variables specific to their project that are NOT used by EDGE. This would include variables used by the NVIDIA driver for example. The appropriate place to override almost all environment variables is in the "DEFINES" block in the user.cfg file. See the "Environment Variables" section below for more info.

user.cfg can be used to either exclude files from the default EDGE load, or to replace those files with user-specific ones. For example, if you are dealing with the default tree.tcl (found in the DSP_CONFIG→DOUG→GUI block of cev.cfg), you will see the line:

tree            "${GUI_HOME}/tree.tcl"

If you want to exclude this file, in your user.cfg, add the line

tree            ""

If you want to replace this file, in your user.cfg, add the line

tree            "${USERDATA}/gui/your_new_replacement_script.tcl"

If you want to see the original tcl file that you just replaced, you might be surprised that it is not in $DOUG_HOME/gui like you would expect! It's hiding, within eng_graph.pkg, which is just like tar or zip or something in between. You get inside the package using the program dsp_package, found in the bin directory. Simply run dsp_package with no arguments, and it will give you a command-line help feature. —smermel

Thanks for the input Scott! With respect to package files, users can look at the Understanding package files article. —FG

Environment Variables

In prior versions of EDGE, environment variables were overridden in the user_env.csh file, but this was limiting once we started moving to the Windows platform. It is now best practice to set all environment variables in the DEFINES block of the user.cfg.

There are many environment variables being used in EDGE, and these are commonly added to and updated with each release. Some of these environment variables may be of more interest to users than others. You can find all of the default settings in the "edge_settings.cfg" file, and copy and paste the variable names into your DEFINES block to override them. You should _NOT_ change them in the edge_settings.cfg file (or any file outside of your userdata for that matter). Some common environment variables you may want to set:

BINARY_MODEL_PATH : sets a colon delimited search path for models

DOUG_STATE_DIR : directory EDGE will default to for loading and saving state files

BASE_STATE : points to the state file loaded at init.

SIM_DATA_DIR : default directory of where the sim data is located for use in the simdata dialog

DOUG_API_FILE : the default API file selected in the simdata dialog

Again, these are just a few. Look through the edge_settings.cfg file in your delivery to see the full list of environment variables being used.

Guiding Principles from Frankie on USERDATA layout

A few notes and suggestions I compiled after many years of seeing USERDATA directories from many different projects:

1. Be sure to add different "LOADS" blocks inside user.cfg to allow the user to select the different scenes and make it obvious where to adjust each scene. And put in the DISPLAY blocks so it is obvious how to select a different display for, say, a single laptop screen or a big TV or something. The load and display can be selected in the run script, which should call a simple script to search for EDGE_HOME if it isn't defined (I have an example I can send you). Also, lots of folks usually want to be able to easily switch between a DCOMM multicast discovery (the default), or a direct comm with a manager where you specify the IP address. I have a simple example script you can source for that as well. This gives a very simple place that folks can see when they startup where to make these most common adjustments.
2. For models, just put model files under $USERDATA/models, and textures in $USERDATA/textures. Avoid environment variables and defines for facilities and projects and vehicles and all that stuff. Just have one place for models. And one file (generally) to put them in ($USERDATA/configs/user_models.cfg). Sometimes it is ok to postload a config file with a bunch of models for a single vehicle if it needs to be shared across some scenes but not others, but in general, I find it better to look through the user_models.cfg file and just have commented sections for each area of models.
3. My guiding principle is - users should have a run script (for each mode or display type), that they can run without providing ANY command line arguments, or setting ANY environment variables. It should look for EDGE if EDGE_HOME isn't defined and just print out what it is using and where it found it if the user doesn't specify. Requiring users to remember command line arguments or set stuff up in the bashrc is just a pain. And it makes making the graphics portable a pain as well.

« Notes about included models | EDGE User’s Guide | Running standalone »