Project Environment

A plugin for SublimeText that allows to set environment variables in the .sublime-project file.

Description:

Variables set with Project Environment are available throughout Sublime. Builds, scripts, even other plugins can relay and use them.

The very nice thing about Project Environment is that all the variables it sets are set per project.
Project Environment can catch when a Sublime's project change and re-set the environment variables accordingly. Even more, if you have two or more Sublime's windows open at the same time, each time you get focus on one of them, Project Environment will run and re-set the variables.

All this is completely transparent to the user.

Settings

there are few settings you can change in ProjectEnvironment.sublime-settings:

• print_output
  When this is set to true, some informations are printed out to console.

• set_sublime_variables
  If true some variables from within Sublime will be set too
  this variables are:
  “project_path”, “project”, “project_name”, “project_base_name”, “packages”

• sublime_variables_prefix
  It may be useful to add a prefix to those variables so that they don't conflict with yours

• sublime_variables_capitalized
  Those variables can be all capitalised if you wish.
  ex: “project” -> “PROJECT”

• command_line_to_wrap_extensions A list of extension that the plugin will treat as command line file. Files with these extension will be “sourced” in an external process and, if they set variables, the environment will be compared to the base environment in Sublime. If there are variables not present in the base Sublime environment, they will be added to it. The default value for this is [".bat", ".sh"]

• execute_ext_with When the env_file (see below) is neither a Json file or one defined in command_line_to_wrap_extensions it will be executed and if it returns a valid Json string, defining a single object (i.e. {"my_var": 1}), it will be used to define the variables in Sublime. Here you can define which program will be used to execute files with a specific extension. Default is:

  "execute_ext_with": {
      ".py": "python"
  }
  

Setup Project Variables

The variables can be set in the “settings” part of a .sublime-project file.
To avoid possible conflicts, the first thing to do is to create a new object in “settings”, called “project_environment”.

"settings":
{
    "project_environment":
    {
    }
}

Inside “project_environment” you can define 5 entries:

• env
• env_file
• windows
• osx
• linux

"settings":
{
    "project_environment":
    {
        "env": {},
      "env_file": "",
        "windows": {},
        "osx": {},
        "linux": {}
    }
}

“env” is for generic, portable environment variable across different systems. “envfile” is a file that can be executed. (see below) _“windows”, “osx” and “linux” are for, obviously, system specific variables.
Please note that none of these are mandatory.

• env is a dictionary. Each "key": "value" pair will be set as environment variable.
• env_file is a path that point to an external file: This file can be:
  • A json file which contains a single object in which variables are defined, similarly to env.
  • An executable. This can be any file that can be executed and it must return a valid Json string which content reflect env The path can be relative to the project file itself (ex: “../../env.sh”)
• windows | osx | linux are object that can contain:
  • env, exactly as the main env, but for system specific variables
  • env_file, like the main env_file except this one can also be a command line file such as .sh, .bat, depending on the operative system. If this file sets variables, those variables will be set also in Sublime. Use this only for system-specific variables.

Note:
The variables in env_file are always set first. This means that env can potentially override what env_file did.

This is an example of a project file:

{
    "folders":
    [
        {
            "path": "."
        }
    ],
    "settings":
    {
        "project_environment":
        {
            "print_output": true,
            "set_sublime_variables": true,
            "sublime_variables_prefix": "sublime_",
            "sublime_variables_capitalized": true,
            "env_file": "./env/generic_env.py"
            "env":
            {
                "CROSS_PLATFORM_ENV": "cross_platform_env"
            },
            "windows":
            {
                "env":
                {
                    "IN_LINE_ENV": "in_line_env_window"
                },
                "env_file": "./env/env_win.bat"
            },
            "osx":
            {
                "env":
                {
                    "IN_LINE_ENV": "in_line_env_mac"
                },
                "env_file": "./env/env_osx.sh"
            },
            "linux":
            {
                "env":
                {
                    "IN_LINE_ENV": "in_line_env_linux"
                },
                "env_file": "./env/env_linux.sh"
            }
        }
    }
}

Resolving Project's paths with variables

Sublime doesn't resolve variables inside project's folders paths. To work around this limitation Project Environment allows you to define another entry alongside a folder path, called path_template.
Project Environment will resolve any environment variable in path_template and replace path with the result.

For example:

{
    "folders":
    [
        {
            "path": ".",
            "path_template": "$MY_PATH"
        }
    ],
    "settings":
    {
        "project_environment":
        {
            "windows":
            {
                "env": { "MY_PATH": "some/location/windows" }
            },
            "osx":
            {
                "env": { "MY_PATH": "some/location/mac_osx" }
            },
            "linux":
            {
                "env": { "MY_PATH": "some/location/linux" }
            }
        }
    }
}

When Project Environment run, automatically or calling the command update_project_data, path will be substituted with the value of MY_PATH and it will be a different value depending on platform running.

Remember
If path_template is present, any value in path will be replaced, so don't set any value in it, because it will be overwritten.

Using the variables in a build_system

Once you have set the variables with Project Environment, you can use it in many different ways. One common use for them is in Sublime's builds.

Imagine you have set a variable called MY_TEST_VARIABLE set to Hello World!!, then you can have:

{
    "name": "Super Test",
    "shell_cmd": "echo %MY_TEST_VARIABLE%"
}

In any window open in Sublime, launching the Super Test builder, and the result will be exactly Hello World!!

{
    "build_systems":
    [
        {
            "name": "Super Test",
            "shell_cmd": "echo %MY_TEST_VARIABLE%"
        }
    ],
    "folders":
    [
        {
            "path": "."
        }
    ],
    "settings":
    {
        "project_environment":
        {
            "env":
            {
                "MY_TEST_VARIABLE": "Hello World!!"
            }
        }
    }
}

A small advise if you work on Linux or Mac

The example above was for Windows, you can do the same for Linux and Mac obviously, but you have to be sure you escape the variable.

{
    "build_systems":
    [
        {
            "name": "Super Test",
            "shell_cmd": "echo \\$MY_TEST_VARIABLE"
        }
    ],
    "folders":
    [
        {
            "path": "."
        }
    ],
    "settings":
    {
        "env":
        {
            "Darwin":
            {
                "MY_TEST_VARIABLE": "Hello World!!"
            }
        }
    }
}

Note the double backslash before $MY_TEST_VARIABLE. This is extremely important. An excerpt from Sublime documentation that explains why:

Variables

[Sublime's] variables will be expanded within any string specified in the “cmd”, “shell_cmd” or “working_dir” options.

If a literal $ needs to be specified in one of these options, it must be escaped with a \. Since JSON uses backslashes for escaping also, $ will need to be written as \\$

How Project Environment collect variables from a command file

When the path to a command file (.bat, .sh, etc) is assigned to env_file, the plugin will run it in a child process*.

It will then collect all the environment variables in that child process and return them to the main process where the new variables, or the variables that have a different values, will be appended to the main environment.

*(using python's subprocess.Popen, with shell=False).

Installation

Using Package Control:

Go to Preferences -> Package Control -> Install Package then type into the text-box “Project Environment”

Click on it, the package will be installed and ready for use.

Using Git:

Locate your Sublime Text Packages directory by using the menu item Preferences -> Browse Packages.

While inside the Packages directory, clone Project Environment in it:
git clone https://bitbucket.org/daniele-niero/sublimeprojectenvironment