helpers/README.txt

LLVM Development Helpers
========================

These files do almost all needed actions for developing LLVM/Clang. They
create the initial source tree, build and test LLVM, coordinate branches
across repositories, control Git/Svn upstream/origin repositories, etc.

All scripts assume you use one of two development modes:

1. Read-Write Git-Svn Mode:

In this mode, all repositories will be based on Git-Svn and setup that way,
with the LLVM SVN repo as the source, the official LLVM Git repo as 'upstream',
a Linaro git repository as 'origin' (populated at prepare phase).

The origin repo is meant to be a back-up and share across Linaro developers,
and since this is public, even external developers. We may use branches on
those repos for Jenkins / Buildbot testing in the future.

All commits will be done via Git-Svn (dcommit) and git-svn-commit will check
if the repo is up-to-date before doing so. It'll also warn if you have more
than one commit, or if you try to commit from master. The former can be
forced, but not the latter.

2. Read-Only Git Mode:

In this mode, the prepare script doesn't setup Git-Svn, and relies only on
LLVM's public Git repo for read-only checkout. You can still have your own
local branches, but they will be de-coupled from the Linaro git tree (unless
you cherry-pick or rebase from them manually).

This type of repo is meant for dev boards, benchmarks and stress tests.

Environment Variables
---------------------

In order to use these scripts, you will have to set the following environment
variables:

LLVM_ROOT    : A path where the scripts can checkout the LLVM & related
               repositories and create build directories for them
LLVM_GITRW   : Git-Read-Write mode, which also means using Git-Svn or not.
               Values can be 'yes' or 'no'.
LLVM_GITUSER : User for 'origin'.
LLVM_SVNUSER : User for the upstream SVN repo (only if LLVM_GITRW = 'yes').

Based on these variables, the llvm-env script sets up the environment needed by
the other helper scripts. You should usually source llvm-env before running any
of the helper scripts.

Dependencies
------------

In order to fully use these scripts, you're going to need to install a few
dependencies. Since people use different Linux distributions, the scripts
don't even try to install that automatically.

The scripts themselves require Git-SVN and a version of Git that can handle
worktrees (e.g. git 2.5.0, may work with earlier versions too).

The requirements for LLVM and the related subprojects are listed in the upstream
documentation:
llvm:        http://llvm.org/docs/GettingStarted.html#requirements
clang:       http://clang.llvm.org/get_started.html
compiler-rt: http://compiler-rt.llvm.org/
lld:         http://lld.llvm.org/getting_started.html
lldb:        http://lldb.llvm.org/build.html
libcxx:      http://libcxx.llvm.org/docs/BuildingLibcxx.html
libcxxabi:   http://libcxxabi.llvm.org/
test-suite:  http://llvm.org/docs/TestingGuide.html#requirements
lnt:         http://llvm.org/docs/lnt/intro.html?highlight=requirements