2.4. Cross-platform considerations

Developers can use a variety of platforms such as Linux and Windows. This section describes how differences between the platforms are handled.

2.4.1. Repository rules

Our rules for end-of-line character sequences, and text file encoding, are as follows:

Warning

Text files, when checked in to the repository, MUST use LF line endings only.

Warning

Text files, when checked in to the repository, MUST be Unicode with UTF-8 encoding.

A daily build job checks that all checked-in text files conform to these rules.

Note

Properties files (*.properties) are ISO-8859-1 by definition (see the docs for the java.util.Properties class). We use Apache Commons Configuration to read our property files (rather than java.util.Properties), but it uses the same default encoding.

2.4.2. How to ensure compliance

  1. Text files checked out from the repository.
    If you only edit the file with Eclipse, the existing (correct) EOL and encoding will be observed, so no specific action is required.
    If you edit the file with some other editor, you need to check what that editor does.
  2. New text files created by Eclipse, and then checked in.
    Before creating any new text files, make sure that Eclipse is set to create text files with the correct attributes.
    This needs to be set separately for each workspace (see Set default line ending and encoding) - if you use the template workspace, this is already set up for you.
  3. Text files created outside Eclipse, and then checked in.
    You need to manage this yourself.

git users (all platforms) should read http://help.github.com/line-endings/, and set:

git config --global core.autocrlf input

Linux users can check line ending characters and encoding by using the file command (it’s correct most of the time), and change it using the dos2unix command:

$ file Version.java
Version.java: UTF-8 Unicode English text, with CRLF line terminators
$ dos2unix Version.java
dos2unix: converting file Version.java to UNIX format ...
$ file Version.java
Version.java: UTF-8 Unicode English text

With some care, you can easily fix up all the invalid line endings within a directory:

bad_text_pattern="text, with\( very long lines, with\)\? CRLF"
# list the files with incorrect file endings
find . -type d -name ".svn" -prune -false -o -type f -exec file {} \; | grep "${bad_text_pattern}" | cut -d':' -f 1
# fix the files with incorrect file endings
find . -type d -name ".svn" -prune -false -o -type f -exec file {} \; | grep "${bad_text_pattern}" | cut -d':' -f 1 | xargs -i --verbose dos2unix {}
# validate the result before checking in, obviously!