Skip to content

EvergreenProperties

Jump to bottom
Martin Dorey edited this page Dec 23, 2020 · 5 revisions

Evergreen Properties

Opening the Properties File

Evergreen properties are found in the evergreen.properties file within the config directory. To open the properties file, do one of the following:

  • Select Preferences from the Edit drop-down menu, and then click on the Open Properties File button in the bottom-left corner of the popup window.
  • Select Evergreen Config Workspace from the Workspace drop-down menu, and then open the evergreen.properties file within the workspace that is created.

Valid Properties

Javadoc Properties

  • java.advisor.doc - Base URL of javadoc (default: http://java.sun.com/javase/6/docs/api/)
  • java.advisor.classpath - Semicolon-separated .jar file locations.
  • java.advisor.doc - Semicolon-separated javadoc locations.

Miscellaneous

  • indentation.allowGuessing - Boolean: whether to allow Evergreen to guess each file's indentation level by processing its content, rather than using the configured value.
  • default.margin - Number of character widths after which to change the background to pale grey rather than white. Only applicable for fixed-width fonts.
  • tags.findTagsTool - Alternative binary for switching to a tag upon a click in the right-hand tags pane. Default is the lib/scripts/find-tags.rb script in the Evergreen directory.
  • saveHook - Program to run after a file is saved from Evergreen. The program will be run with the saved filename as argument.
  • default.linkRegexp.<regexp>=<link> - Language-agnostic rule for highlighting specific patterns as hyperlinks (eg links to bug databases). See the link regexps section for details.

FileType-Specific

The following properties include the filetype in their name, to allow a property to be set differently per language. For example, you might want an 80-char margin for C++, but 100 chars for Java.

  • <language>.margin - Number of character widths after which to change the background to pale grey rather than white. Only applicable for fixed-width fonts. This property will override the default.margin property when set.
  • <language>.lintChecker - Program to run when the user selects the Check For Lint built-in tool. The program will be run with the filename as argument.
  • <language>.linkRegexp.<regexp>=<link> - Language-specific rule for highlighting specific patterns as hyperlinks (eg links to bug databases). See the link regexps section for details.

Build Tools

Evergreen identifies which build tool to run based on the presence of specifically-named files. For example, if it sees a file called Makefile it will by default run make --print-directory when the build action is invoked.

Defaults are provided for files called CMakeLists.txt, Makefile, build.xml and meson.build. If you're using another build system, or indeed if you wish to override the default behaviour for any of the above, you can provide a script to run by setting a property:

  • build.<filename> - The command to run when the build action is invoked, and <filename> is present in the directory (or in a parent directory).

Unit Test Files

Evergreen has support for finding your unit test files, and quickly opening them. However, you have to configure this, as choices on the naming and location of unit test files are quite varied. The location mapping is defined by regexp mappings configured with the testFilenameMapping. prefix. In general:

  • testFilenameMapping.<regexp>=<replacement> - If a filename matches <regexp>, the test file will be sought by looking for <replacement>.

For example, if our source code is set up such that C++ files have a .cc extension, and their corresponding test files will be named ..._test.cc, we might write:

testFilenameMapping.(.*)\.cc=$1_test.cc

If, on the other hand, we use a subdirectory for java tests such that the test for foo/MyClass.java will be found in foo/tests/TestMyClass.java, we could write:

testFilenameMapping.(.*)/([^/.]+)\.java=$1/tests/Test$2.java

Link Regexps

Evergreen allows you to configure language-specific and -agnostic regexp patterns which, when matched, highlight the selected text and turn it into a hyperlink.

Such links will only be effective when within a comment (or in a plain text document).

Each regexp must contain at least two capturing groups. The first group identifies the part of the text to be highlighted as a link (and is usually the entire matching text). The second group matches the part of the text to be substituted into the URL.

For example, if we work at a company where bugs are generally referred to using the pattern "bug:12345", and the corresponding bug database link would be http://bugzrus.example.com/bugid=12345, then we might add the rule:

default.linkRegexp.(bug:(\d+))=http://bugzrus.example.com/bugid=%s

The outer set of parentheses show that we want the entire "bug:12345" to be linked; the inner set identify one or more digits, and will form matching group 2. The value is a partial URL, with a "%s" to show where group 2 ("12345") is to be substituted.

Of course, this is not restricted to bug databases; you could also provide easy lookups for colleagues who've left TODO messages in code. For example, if we were to do this only in C++ code, we could write:

C++.linkRegexp.(TODO(\w+))=http://people.hr.example.com/?username=%s

If your regexp does not contain at least one matching group, no links will show up, and you'll get a lot of spammy log messages. If it contains only one matching group, the hyperlink will link to the Error: Group Count section on this page.

The %s field is URL-encoded, so it can safely include any character. That causes a problem for section references. https://github.com/software-jessies-org/jessies/wiki/%45vergreenProperties points to this page and https://github.com/software-jessies-org/jessies/wiki/EvergreenProperties#link-regexps points to a section in this page but URL-encoding the # results in https://github.com/software-jessies-org/jessies/wiki/EvergreenProperties%23link-regexps which tries to create a new page. The solution is an optional third group, for a section label that will be appended, URL-encoded, following a # that isn't URL-encoded.

Languages

Several of the properties are language-specific. The following are the names of the languages Evergreen supports:

  • Assembler
  • Bash
  • C#
  • C++
  • Email
  • Go
  • Java
  • JavaScript
  • Make
  • Patch
  • Perl
  • PHP
  • Plain Text
  • Protocol Buffer
  • Python
  • Ruby
  • Rust
  • VHDL
  • XML

Error: Group Count

If you were sent here by a link you tried to configure in Evergreen, then this message is to let you know that the syntax of your regular expression isn't quite enough for what we need. The regexp must contain at least two capturing groups. The first capturing group is the part of the text that should be highlighted; the second is the part which is substituted into the URL.

Please see the examples in the link regexps section.

Clone this wiki locally