mirror of
https://github.com/RPCS3/llvm.git
synced 2025-02-12 13:48:45 +00:00
Update GettingStarted guide to recommend that people use the new
official Git repository. Remove the directions for using git-svn, and demote the prominence of the svn instructions. Also, fix a few other issues while I'm in there: * Mention LLVM_ENABLE_PROJECTS more. * Getting started doesn't need to mention test-suite, but should mention clang and the other projects. * Remove mentions of "configure", since that's long gone. I've also adjusted a few other mentions of svn to point to github, but have not done so comprehensively. Differential Revision: https://reviews.llvm.org/D56654 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@351130 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
parent
f0a0953bb6
commit
8986b31304
@ -22,7 +22,7 @@ This policy is also designed to accomplish the following objectives:
|
||||
|
||||
#. Make life as simple and easy for contributors as possible.
|
||||
|
||||
#. Keep the top of Subversion trees as stable as possible.
|
||||
#. Keep the tip of tree as stable as possible.
|
||||
|
||||
#. Establish awareness of the project's :ref:`copyright, license, and patent
|
||||
policies <copyright-license-patents>` with contributors to the project.
|
||||
@ -80,23 +80,19 @@ Making and Submitting a Patch
|
||||
When making a patch for review, the goal is to make it as easy for the reviewer
|
||||
to read it as possible. As such, we recommend that you:
|
||||
|
||||
#. Make your patch against the Subversion trunk, not a branch, and not an old
|
||||
version of LLVM. This makes it easy to apply the patch. For information on
|
||||
how to check out SVN trunk, please see the `Getting Started
|
||||
Guide <GettingStarted.html#checkout>`_.
|
||||
#. Make your patch against git master, not a branch, and not an old version
|
||||
of LLVM. This makes it easy to apply the patch. For information on how to
|
||||
clone from git, please see the :ref:`Getting Started Guide
|
||||
<checkout>`.
|
||||
|
||||
#. Similarly, patches should be submitted soon after they are generated. Old
|
||||
patches may not apply correctly if the underlying code changes between the
|
||||
time the patch was created and the time it is applied.
|
||||
|
||||
#. Patches should be made with ``svn diff``, or similar. If you use a
|
||||
#. Patches should be made with ``git format-patch``, or similar. If you use a
|
||||
different tool, make sure it uses the ``diff -u`` format and that it
|
||||
doesn't contain clutter which makes it hard to read.
|
||||
|
||||
#. If you are modifying generated files, such as the top-level ``configure``
|
||||
script, please separate out those changes into a separate patch from the rest
|
||||
of your changes.
|
||||
|
||||
Once your patch is ready, submit it by emailing it to the appropriate project's
|
||||
commit mailing list (or commit it directly if applicable). Alternatively, some
|
||||
patches get sent to the project's development list or component of the LLVM bug
|
||||
@ -187,9 +183,9 @@ someone else will review it, allowing the patch to go unreviewed. To solve this
|
||||
problem, we have a notion of an 'owner' for a piece of the code. The sole
|
||||
responsibility of a code owner is to ensure that a commit to their area of the
|
||||
code is appropriately reviewed, either by themself or by someone else. The list
|
||||
of current code owners can be found in the file
|
||||
`CODE_OWNERS.TXT <http://git.llvm.org/klaus/llvm/blob/master/CODE_OWNERS.TXT>`_
|
||||
in the root of the LLVM source tree.
|
||||
of current code owners can be found in the file `CODE_OWNERS.TXT
|
||||
<https://github.com/llvm/llvm-project/blob/master/llvm/CODE_OWNERS.TXT>`_ in the
|
||||
root of the LLVM source tree.
|
||||
|
||||
Note that code ownership is completely different than reviewers: anyone can
|
||||
review a piece of code, and we welcome code review from anyone who is
|
||||
|
@ -8,23 +8,22 @@ Getting Started with the LLVM System
|
||||
Overview
|
||||
========
|
||||
|
||||
Welcome to LLVM! In order to get started, you first need to know some basic
|
||||
information.
|
||||
Welcome to the LLVM project! In order to get started, you first need to know
|
||||
some basic information.
|
||||
|
||||
First, LLVM comes in three pieces. The first piece is the LLVM suite. This
|
||||
contains all of the tools, libraries, and header files needed to use LLVM. It
|
||||
contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It
|
||||
also contains basic regression tests that can be used to test the LLVM tools and
|
||||
the Clang front end.
|
||||
First, the LLVM project has multiple components. The core of the project is
|
||||
itself called "LLVM". This contains all of the tools, libraries, and header
|
||||
files needed to process an intermediate representation and convert it into
|
||||
object files. It contains an assembler, disassembler, bitcode analyzer and
|
||||
bitcode optimizer. It also contains basic regression tests.
|
||||
|
||||
The second piece is the `Clang <http://clang.llvm.org/>`_ front end. This
|
||||
component compiles C, C++, Objective C, and Objective C++ code into LLVM
|
||||
bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the
|
||||
LLVM tools from the LLVM suite.
|
||||
Another piece is the `Clang <http://clang.llvm.org/>`_ front end. This
|
||||
component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode
|
||||
-- and from there into object files, using LLVM.
|
||||
|
||||
There is a third, optional piece called Test Suite. It is a suite of programs
|
||||
with a testing harness that can be used to further test LLVM's functionality
|
||||
and performance.
|
||||
There are other components as well:
|
||||
the `libc++ C++ standard library <https://libcxx.llvm.org>`_,
|
||||
the `LLD linker <https://lld.llvm.org>`_, and more.
|
||||
|
||||
Getting Started Quickly (A Summary)
|
||||
===================================
|
||||
@ -39,90 +38,38 @@ Here's the short story for getting up and running quickly with LLVM:
|
||||
#. Read the documentation.
|
||||
#. Remember that you were warned twice about reading the documentation.
|
||||
|
||||
* In particular, the *relative paths specified are important*.
|
||||
#. Checkout LLVM (including related subprojects like Clang):
|
||||
|
||||
#. Checkout LLVM:
|
||||
* ``git clone https://github.com/llvm/llvm-project.git``
|
||||
* Or, on windows, ``git clone --config core.autocrlf=false
|
||||
https://github.com/llvm/llvm-project.git``
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
|
||||
#. Configure and build LLVM and Clang:.
|
||||
|
||||
#. Checkout Clang:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/tools``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
|
||||
|
||||
#. Checkout Extra Clang Tools **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/tools/clang/tools``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
|
||||
|
||||
#. Checkout LLD linker **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/tools``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/lld/trunk lld``
|
||||
|
||||
#. Checkout Polly Loop Optimizer **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/tools``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/polly/trunk polly``
|
||||
|
||||
#. Checkout Compiler-RT (required to build the sanitizers) **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/projects``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
|
||||
|
||||
#. Checkout Libomp (required for OpenMP support) **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/projects``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/openmp/trunk openmp``
|
||||
|
||||
#. Checkout libcxx and libcxxabi **[Optional]**:
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/projects``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
|
||||
|
||||
#. Get the Test Suite Source Code **[Optional]**
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* ``cd llvm/projects``
|
||||
* ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite``
|
||||
|
||||
#. Configure and build LLVM and Clang:
|
||||
|
||||
*Warning:* Make sure you've checked out *all of* the source code
|
||||
before trying to configure with cmake. cmake does not pickup newly
|
||||
added source directories in incremental builds.
|
||||
|
||||
The build uses `CMake <CMake.html>`_. LLVM requires CMake 3.4.3 to build. It
|
||||
is generally recommended to use a recent CMake, especially if you're
|
||||
generating Ninja build files. This is because the CMake project is constantly
|
||||
improving the quality of the generators, and the Ninja generator gets a lot
|
||||
of attention.
|
||||
|
||||
* ``cd where you want to build llvm``
|
||||
* ``cd llvm-project``
|
||||
* ``mkdir build``
|
||||
* ``cd build``
|
||||
* ``cmake -G <generator> [options] <path to llvm sources>``
|
||||
* ``cmake -G <generator> [options] ../llvm``
|
||||
|
||||
Some common generators are:
|
||||
|
||||
* ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
|
||||
* ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_
|
||||
build files. Most llvm developers use Ninja.
|
||||
* ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
|
||||
* ``Visual Studio`` --- for generating Visual Studio projects and
|
||||
solutions.
|
||||
* ``Xcode`` --- for generating Xcode projects.
|
||||
|
||||
Some Common options:
|
||||
|
||||
* ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
|
||||
subprojects you'd like to additionally build. Can include any of: clang,
|
||||
libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld, polly, or
|
||||
debuginfo-tests.
|
||||
|
||||
For example, to build LLVM, Clang, libcxx, and libcxxabi, use
|
||||
``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
|
||||
|
||||
* ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
|
||||
pathname of where you want the LLVM tools and libraries to be installed
|
||||
(default ``/usr/local``).
|
||||
@ -135,16 +82,18 @@ Here's the short story for getting up and running quickly with LLVM:
|
||||
|
||||
* Run your build tool of choice!
|
||||
|
||||
* The default target (i.e. ``make``) will build all of LLVM
|
||||
* The default target (i.e. ``ninja`` or ``make``) will build all of LLVM.
|
||||
|
||||
* The ``check-all`` target (i.e. ``make check-all``) will run the
|
||||
* The ``check-all`` target (i.e. ``ninja check-all``) will run the
|
||||
regression tests to ensure everything is in working order.
|
||||
|
||||
* CMake will generate build targets for each tool and library, and most
|
||||
LLVM sub-projects generate their own ``check-<project>`` target.
|
||||
|
||||
* Running a serial build will be *slow*. Make sure you run a
|
||||
parallel build; for ``make``, use ``make -j``.
|
||||
* Running a serial build will be *slow*. Make sure you run a parallel
|
||||
build. That's already done by default in Ninja; for ``make``, use
|
||||
``make -j NNN`` (with an appropriate value of NNN, e.g. number of CPUs
|
||||
you have.)
|
||||
|
||||
* For more information see `CMake <CMake.html>`_
|
||||
|
||||
@ -172,7 +121,7 @@ OS Arch Compilers
|
||||
================== ===================== =============
|
||||
Linux x86\ :sup:`1` GCC, Clang
|
||||
Linux amd64 GCC, Clang
|
||||
Linux ARM\ :sup:`4` GCC, Clang
|
||||
Linux ARM GCC, Clang
|
||||
Linux PowerPC GCC, Clang
|
||||
Solaris V9 (Ultrasparc) GCC
|
||||
FreeBSD x86\ :sup:`1` GCC, Clang
|
||||
@ -192,7 +141,6 @@ Windows x64 x86-64 Visual Studio
|
||||
#. Code generation supported for 32-bit ABI only
|
||||
#. To use LLVM modules on Win32-based system, you may configure LLVM
|
||||
with ``-DBUILD_SHARED_LIBS=On``.
|
||||
#. MCJIT not working well pre-v7, old JIT engine not supported any more.
|
||||
|
||||
Note that Debug builds require a lot of time and disk space. An LLVM-only build
|
||||
will need about 1-3 GB of space. A full build of LLVM and Clang will need around
|
||||
@ -433,10 +381,9 @@ Unpacking the LLVM Archives
|
||||
---------------------------
|
||||
|
||||
If you have the LLVM distribution, you will need to unpack it before you can
|
||||
begin to compile it. LLVM is distributed as a set of two files: the LLVM suite
|
||||
and the LLVM GCC front end compiled for your platform. There is an additional
|
||||
test suite that is optional. Each file is a TAR archive that is compressed with
|
||||
the gzip program.
|
||||
begin to compile it. LLVM is distributed as a number of different
|
||||
subprojects. Each one has its own download which is a TAR archive that is
|
||||
compressed with the gzip program.
|
||||
|
||||
The files are as follows, with *x.y* marking the version number:
|
||||
|
||||
@ -444,18 +391,132 @@ The files are as follows, with *x.y* marking the version number:
|
||||
|
||||
Source release for the LLVM libraries and tools.
|
||||
|
||||
``llvm-test-x.y.tar.gz``
|
||||
``cfe-x.y.tar.gz``
|
||||
|
||||
Source release for the LLVM test-suite.
|
||||
Source release for the Clang frontend.
|
||||
|
||||
.. _checkout:
|
||||
|
||||
Checkout LLVM from Subversion
|
||||
-----------------------------
|
||||
Checkout LLVM from Git
|
||||
----------------------
|
||||
|
||||
If you have access to our Subversion repository, you can get a fresh copy of the
|
||||
entire source code. All you need to do is check it out from Subversion as
|
||||
follows:
|
||||
You can also checkout the source code for LLVM from Git. While the LLVM
|
||||
project's official source-code repository is Subversion, we are in the process
|
||||
of migrating to git. We currently recommend that all developers use Git for
|
||||
day-to-day development.
|
||||
|
||||
.. note::
|
||||
|
||||
Passing ``--config core.autocrlf=false`` should not be required in
|
||||
the future after we adjust the .gitattribute settings correctly, but
|
||||
is required for Windows users at the time of this writing.
|
||||
|
||||
Simply run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git clone https://github.com/llvm/llvm-project.git`
|
||||
|
||||
or on Windows,
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git clone --config core.autocrlf=false https://github.com/llvm/llvm-project.git
|
||||
|
||||
This will create an '``llvm-project``' directory in the current directory and
|
||||
fully populate it with all of the source code, test directories, and local
|
||||
copies of documentation files for LLVM and all the related subprojects. Note
|
||||
that unlike the tarballs, which contain each subproject in a separate file, the
|
||||
git repository contains all of the projects together.
|
||||
|
||||
If you want to get a specific release (as opposed to the most recent revision),
|
||||
you can check out a tag after cloning the repository. E.g., `git checkout
|
||||
llvmorg-6.0.1` inside the ``llvm-project`` directory created by the above
|
||||
command. Use `git tag -l` to list all of them.
|
||||
|
||||
Sending patches
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too.
|
||||
|
||||
We don't currently accept github pull requests, so you'll need to send patches
|
||||
either via emailing to llvm-commits, or, preferably, via :ref:`Phabricator
|
||||
<phabricator-reviews>`.
|
||||
|
||||
You'll generally want to make sure your branch has a single commit,
|
||||
corresponding to the review you wish to send, up-to-date with the upstream
|
||||
``origin/master`` branch, and doesn't contain merges. Once you have that, you
|
||||
can use ``git show`` or ``git format-patch`` to output the diff, and attach it
|
||||
to a Phabricator review (or to an email message).
|
||||
|
||||
However, using the "Arcanist" tool is often easier. After `installing
|
||||
arcanist`_, you can upload the latest commit using:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% arc diff HEAD~1
|
||||
|
||||
Additionally, before sending a patch for review, please also try to ensure it's
|
||||
formatted properly. We use ``clang-format`` for this, which has git integration
|
||||
through the ``git-clang-format`` script. On some systems, it may already be
|
||||
installed (or be installable via your package manager). If so, you can simply
|
||||
run it -- the following command will format only the code changed in the most
|
||||
recent commit:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git clang-format HEAD~1
|
||||
|
||||
Note that this modifies the files, but doesn't commit them -- you'll likely want
|
||||
to run
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git commit --amend -a
|
||||
|
||||
in order to update the last commit with all pending changes.
|
||||
|
||||
.. note::
|
||||
If you don't already have ``clang-format`` or ``git clang-format`` installed
|
||||
on your system, the ``clang-format`` binary will be built alongside clang, and
|
||||
the git integration can be run from
|
||||
``clang/tools/clang-format/git-clang-format``.
|
||||
|
||||
|
||||
.. _commit_from_git:
|
||||
|
||||
For developers to commit changes from Git
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it
|
||||
to your path, you can push committed changes upstream with ``git llvm
|
||||
push``. While this creates a Subversion checkout and patches it under the hood,
|
||||
it does not require you to have interaction with it.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% export PATH=$PATH:$TOP_LEVEL_DIR/llvm-project/llvm/utils/git-svn/
|
||||
% git llvm push
|
||||
|
||||
Within a couple minutes after pushing to subversion, the svn commit will have
|
||||
been converted back to a Git commit, and made its way into the official Git
|
||||
repository. At that point, ``git pull`` should get back the changes as they were
|
||||
committed.
|
||||
|
||||
You'll likely want to ``git pull --rebase`` to get the official git commit
|
||||
downloaded back to your repository. The SVN revision numbers of each commit can
|
||||
be found at the end of the commit message, e.g. ``llvm-svn: 350914``.
|
||||
|
||||
You may also find the ``-n`` flag useful, like ``git llvm push -n``. This runs
|
||||
through all the steps of committing _without_ actually doing the commit, and
|
||||
tell you what it would have done. That can be useful if you're unsure whether
|
||||
the right thing will happen.
|
||||
|
||||
Checkout via SVN (deprecated)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Until we have fully migrated to Git, you may also get a fresh copy of
|
||||
the code from the official Subversion repository.
|
||||
|
||||
* ``cd where-you-want-llvm-to-live``
|
||||
* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
|
||||
@ -475,305 +536,13 @@ directory:
|
||||
* Release 1.1 through 2.8: **RELEASE_11** and so on
|
||||
* Release 1.0: **RELEASE_1**
|
||||
|
||||
If you would like to get the LLVM test suite (a separate package as of 1.4), you
|
||||
get it from the Subversion repository:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/projects
|
||||
% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
|
||||
|
||||
By placing it in the ``llvm/projects``, it will be automatically configured by
|
||||
the LLVM cmake configuration.
|
||||
|
||||
Git Mirror
|
||||
----------
|
||||
|
||||
Git mirrors are available for a number of LLVM subprojects. These mirrors sync
|
||||
automatically with each Subversion commit and contain all necessary git-svn
|
||||
marks (so, you can recreate git-svn metadata locally). Note that right now
|
||||
mirrors reflect only ``trunk`` for each project.
|
||||
|
||||
.. note::
|
||||
|
||||
On Windows, first you will want to do ``git config --global core.autocrlf
|
||||
false`` before you clone. This goes a long way toward ensuring that
|
||||
line-endings will be handled correctly (the LLVM project mostly uses Linux
|
||||
line-endings).
|
||||
|
||||
You can do the read-only Git clone of LLVM via:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git clone https://git.llvm.org/git/llvm.git/
|
||||
|
||||
If you want to check out clang too, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/tools
|
||||
% git clone https://git.llvm.org/git/clang.git/
|
||||
|
||||
If you want to check out compiler-rt (required to build the sanitizers), run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/projects
|
||||
% git clone https://git.llvm.org/git/compiler-rt.git/
|
||||
|
||||
If you want to check out libomp (required for OpenMP support), run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/projects
|
||||
% git clone https://git.llvm.org/git/openmp.git/
|
||||
|
||||
If you want to check out libcxx and libcxxabi (optional), run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/projects
|
||||
% git clone https://git.llvm.org/git/libcxx.git/
|
||||
% git clone https://git.llvm.org/git/libcxxabi.git/
|
||||
|
||||
If you want to check out the Test Suite Source Code (optional), run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd llvm/projects
|
||||
% git clone https://git.llvm.org/git/test-suite.git/
|
||||
|
||||
Since the upstream repository is in Subversion, you should use ``git
|
||||
pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history
|
||||
in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the
|
||||
master branch, run the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git config branch.master.rebase true
|
||||
|
||||
Sending patches with Git
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too.
|
||||
|
||||
Assume ``master`` points the upstream and ``mybranch`` points your working
|
||||
branch, and ``mybranch`` is rebased onto ``master``. At first you may check
|
||||
sanity of whitespaces:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git diff --check master..mybranch
|
||||
|
||||
The easiest way to generate a patch is as below:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git diff master..mybranch > /path/to/mybranch.diff
|
||||
|
||||
It is a little different from svn-generated diff. git-diff-generated diff has
|
||||
prefixes like ``a/`` and ``b/``. Don't worry, most developers might know it
|
||||
could be accepted with ``patch -p1 -N``.
|
||||
|
||||
But you may generate patchset with git-format-patch. It generates by-each-commit
|
||||
patchset. To generate patch files to attach to your article:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git format-patch --no-attach master..mybranch -o /path/to/your/patchset
|
||||
|
||||
If you would like to send patches directly, you may use git-send-email or
|
||||
git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git format-patch --attach master..mybranch --stdout | git imap-send
|
||||
|
||||
Then, your .git/config should have [imap] sections.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[imap]
|
||||
host = imaps://imap.gmail.com
|
||||
user = your.gmail.account@gmail.com
|
||||
pass = himitsu!
|
||||
port = 993
|
||||
sslverify = false
|
||||
; in English
|
||||
folder = "[Gmail]/Drafts"
|
||||
; example for Japanese, "Modified UTF-7" encoded.
|
||||
folder = "[Gmail]/&Tgtm+DBN-"
|
||||
; example for Traditional Chinese
|
||||
folder = "[Gmail]/&g0l6Pw-"
|
||||
|
||||
.. _developers-work-with-git-svn:
|
||||
|
||||
For developers to work with git-svn
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To set up clone from which you can submit code using ``git-svn``, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git clone https://git.llvm.org/git/llvm.git/
|
||||
% cd llvm
|
||||
% git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
|
||||
% git config svn-remote.svn.fetch :refs/remotes/origin/master
|
||||
% git svn rebase -l # -l avoids fetching ahead of the git mirror.
|
||||
|
||||
# If you have clang too:
|
||||
% cd tools
|
||||
% git clone https://git.llvm.org/git/clang.git/
|
||||
% cd clang
|
||||
% git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username>
|
||||
% git config svn-remote.svn.fetch :refs/remotes/origin/master
|
||||
% git svn rebase -l
|
||||
|
||||
Likewise for compiler-rt, libomp and test-suite.
|
||||
|
||||
To update this clone without generating git-svn tags that conflict with the
|
||||
upstream Git repo, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees.
|
||||
% git checkout master
|
||||
% git svn rebase -l
|
||||
% (cd tools/clang &&
|
||||
git checkout master &&
|
||||
git svn rebase -l)
|
||||
|
||||
Likewise for compiler-rt, libomp and test-suite.
|
||||
|
||||
This leaves your working directories on their master branches, so you'll need to
|
||||
``checkout`` each working branch individually and ``rebase`` it on top of its
|
||||
parent branch.
|
||||
|
||||
For those who wish to be able to update an llvm repo/revert patches easily using
|
||||
git-svn, please look in the directory for the scripts ``git-svnup`` and
|
||||
``git-svnrevert``.
|
||||
|
||||
To perform the aforementioned update steps go into your source directory and
|
||||
just type ``git-svnup`` or ``git svnup`` and everything will just work.
|
||||
|
||||
If one wishes to revert a commit with git-svn, but do not want the git hash to
|
||||
escape into the commit message, one can use the script ``git-svnrevert`` or
|
||||
``git svnrevert`` which will take in the git hash for the commit you want to
|
||||
revert, look up the appropriate svn revision, and output a message where all
|
||||
references to the git hash have been replaced with the svn revision.
|
||||
|
||||
To commit back changes via git-svn, use ``git svn dcommit``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git svn dcommit
|
||||
|
||||
Note that git-svn will create one SVN commit for each Git commit you have pending,
|
||||
so squash and edit each commit before executing ``dcommit`` to make sure they all
|
||||
conform to the coding standards and the developers' policy.
|
||||
|
||||
On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict,
|
||||
please make sure your current branch is up-to-date (via fetch/rebase) before
|
||||
proceeding.
|
||||
|
||||
The git-svn metadata can get out of sync after you mess around with branches and
|
||||
``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining
|
||||
about files with uncommitted changes. The fix is to rebuild the metadata:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% rm -rf .git/svn
|
||||
% git svn rebase -l
|
||||
|
||||
Please, refer to the Git-SVN manual (``man git-svn``) for more information.
|
||||
|
||||
For developers to work with a git monorepo
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. note::
|
||||
|
||||
This set-up is using an unofficial mirror hosted on GitHub, use with caution.
|
||||
|
||||
To set up a clone of all the llvm projects using a unified repository:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% export TOP_LEVEL_DIR=`pwd`
|
||||
% git clone https://github.com/llvm-project/llvm-project-20170507/ llvm-project
|
||||
% cd llvm-project
|
||||
% git config branch.master.rebase true
|
||||
|
||||
You can configure various build directory from this clone, starting with a build
|
||||
of LLVM alone:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd $TOP_LEVEL_DIR
|
||||
% mkdir llvm-build && cd llvm-build
|
||||
% cmake -GNinja ../llvm-project/llvm
|
||||
|
||||
Or lldb:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd $TOP_LEVEL_DIR
|
||||
% mkdir lldb-build && cd lldb-build
|
||||
% cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS=lldb
|
||||
|
||||
Or a combination of multiple projects:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd $TOP_LEVEL_DIR
|
||||
% mkdir clang-build && cd clang-build
|
||||
% cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"
|
||||
|
||||
A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it
|
||||
to your path, you can push committed changes upstream with ``git llvm push``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% export PATH=$PATH:$TOP_LEVEL_DIR/llvm-project/llvm/utils/git-svn/
|
||||
% git llvm push
|
||||
|
||||
While this is using SVN under the hood, it does not require any interaction from
|
||||
you with git-svn.
|
||||
After a few minutes, ``git pull`` should get back the changes as they were
|
||||
committed. Note that a current limitation is that ``git`` does not directly
|
||||
record file rename, and thus it is propagated to SVN as a combination of
|
||||
delete-add instead of a file rename.
|
||||
|
||||
The SVN revision of each monorepo commit can be found in the commit notes. git
|
||||
does not fetch notes by default. The following commands will fetch the notes and
|
||||
configure git to fetch future notes. Use ``git notes show $commit`` to look up
|
||||
the SVN revision of a git commit. The notes show up ``git log``, and searching
|
||||
the log is currently the recommended way to look up the git commit for a given
|
||||
SVN revision.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% git config --add remote.origin.fetch +refs/notes/commits:refs/notes/commits
|
||||
% git fetch
|
||||
|
||||
If you are using `arc` to interact with Phabricator, you need to manually put it
|
||||
at the root of the checkout:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
% cd $TOP_LEVEL_DIR
|
||||
% cp llvm/.arcconfig ./
|
||||
% mkdir -p .git/info/
|
||||
% echo .arcconfig >> .git/info/exclude
|
||||
|
||||
|
||||
Local LLVM Configuration
|
||||
------------------------
|
||||
|
||||
Once checked out from the Subversion repository, the LLVM suite source code must
|
||||
be configured before being built. This process uses CMake.
|
||||
Unlinke the normal ``configure`` script, CMake
|
||||
generates the build files in whatever format you request as well as various
|
||||
``*.inc`` files, and ``llvm/include/Config/config.h``.
|
||||
Once checked out repository, the LLVM suite source code must be configured
|
||||
before being built. This process uses CMake. Unlinke the normal ``configure``
|
||||
script, CMake generates the build files in whatever format you request as well
|
||||
as various ``*.inc`` files, and ``llvm/include/Config/config.h``.
|
||||
|
||||
Variables are passed to ``cmake`` on the command line using the format
|
||||
``-D<variable name>=<value>``. The following variables are some common options
|
||||
@ -797,19 +566,26 @@ used by people developing LLVM.
|
||||
| | running the install action of the build files. |
|
||||
+-------------------------+----------------------------------------------------+
|
||||
| LLVM_TARGETS_TO_BUILD | A semicolon delimited list controlling which |
|
||||
| | targets will be built and linked into llc. This is |
|
||||
| | equivalent to the ``--enable-targets`` option in |
|
||||
| | the configure script. The default list is defined |
|
||||
| | as ``LLVM_ALL_TARGETS``, and can be set to include |
|
||||
| | targets will be built and linked into llvm. |
|
||||
| | The default list is defined as |
|
||||
| | ``LLVM_ALL_TARGETS``, and can be set to include |
|
||||
| | out-of-tree targets. The default value includes: |
|
||||
| | ``AArch64, AMDGPU, ARM, BPF, Hexagon, Mips, |
|
||||
| | MSP430, NVPTX, PowerPC, Sparc, SystemZ, X86, |
|
||||
| | XCore``. |
|
||||
| | |
|
||||
+-------------------------+----------------------------------------------------+
|
||||
| LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source |
|
||||
| | code This is disabled by default because it is |
|
||||
| | slow and generates a lot of output. |
|
||||
+-------------------------+----------------------------------------------------+
|
||||
| LLVM_ENABLE_PROJECTS | A semicolon-delimited list selecting which of the |
|
||||
| | other LLVM subprojects to additionally build. (Only|
|
||||
| | effective when using a side-by-side project layout |
|
||||
| | e.g. via git). The default list is empty. Can |
|
||||
| | include: clang, libcxx, libcxxabi, libunwind, lldb,|
|
||||
| | compiler-rt, lld, polly, or debuginfo-tests. |
|
||||
+-------------------------+----------------------------------------------------+
|
||||
| LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source |
|
||||
| | code. This is disabled by default because it is |
|
||||
| | slow and generates a lot of output. Sphinx version |
|
||||
@ -1030,10 +806,10 @@ Public header files exported from the LLVM library. The three main subdirectorie
|
||||
|
||||
``llvm/include/llvm/Config``
|
||||
|
||||
Header files configured by the ``configure`` script.
|
||||
They wrap "standard" UNIX and C header files. Source code can include these
|
||||
header files which automatically take care of the conditional #includes that
|
||||
the ``configure`` script generates.
|
||||
Header files configured by ``cmake``. They wrap "standard" UNIX and
|
||||
C header files. Source code can include these header files which
|
||||
automatically take care of the conditional #includes that ``cmake``
|
||||
generates.
|
||||
|
||||
``llvm/lib``
|
||||
------------
|
||||
@ -1105,10 +881,11 @@ are intended to run quickly and cover a lot of territory without being exhaustiv
|
||||
``test-suite``
|
||||
--------------
|
||||
|
||||
A comprehensive correctness, performance, and benchmarking test suite for LLVM.
|
||||
Comes in a separate Subversion module because not every LLVM user is interested
|
||||
in such a comprehensive suite. For details see the :doc:`Testing Guide
|
||||
<TestingGuide>` document.
|
||||
A comprehensive correctness, performance, and benchmarking test suite
|
||||
for LLVM. This comes in a ``separate git repository
|
||||
<https://github.com/llvm/llvm-test-suite>``, because it contains a
|
||||
large amount of third-party code under a variety of licenses. For
|
||||
details see the :doc:`Testing Guide <TestingGuide>` document.
|
||||
|
||||
.. _tools:
|
||||
|
||||
@ -1322,3 +1099,5 @@ write something up!). For more information about LLVM, check out:
|
||||
* `LLVM Homepage <http://llvm.org/>`_
|
||||
* `LLVM Doxygen Tree <http://llvm.org/doxygen/>`_
|
||||
* `Starting a Project that Uses LLVM <http://llvm.org/docs/Projects.html>`_
|
||||
|
||||
.. _installing arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/
|
||||
|
@ -1,3 +1,5 @@
|
||||
.. _phabricator-reviews:
|
||||
|
||||
=============================
|
||||
Code Reviews with Phabricator
|
||||
=============================
|
||||
@ -16,7 +18,7 @@ to respond to free-form comments in mail sent to the commits list.
|
||||
Sign up
|
||||
-------
|
||||
|
||||
To get started with Phabricator, navigate to `http://reviews.llvm.org`_ and
|
||||
To get started with Phabricator, navigate to `https://reviews.llvm.org`_ and
|
||||
click the power icon in the top right. You can register with a GitHub account,
|
||||
a Google account, or you can create your own profile.
|
||||
|
||||
@ -151,7 +153,7 @@ ends with the line:
|
||||
Differential Revision: <URL>
|
||||
|
||||
where ``<URL>`` is the URL for the code review, starting with
|
||||
``http://reviews.llvm.org/``.
|
||||
``https://reviews.llvm.org/``.
|
||||
|
||||
This allows people reading the version history to see the review for
|
||||
context. This also allows Phabricator to detect the commit, close the
|
||||
@ -162,11 +164,11 @@ be added automatically. If you don't want to use Arcanist, you can add the
|
||||
``Differential Revision`` line (as the last line) to the commit message
|
||||
yourself.
|
||||
|
||||
Using the Arcanist tool can simplify the process of committing reviewed code
|
||||
as it will retrieve reviewers, the ``Differential Revision``, etc from the review
|
||||
and place it in the commit message. Several methods of using Arcanist to commit
|
||||
code are given below. If you do not wish to use Arcanist then simply commit
|
||||
the reviewed patch as you would normally.
|
||||
Using the Arcanist tool can simplify the process of committing reviewed code as
|
||||
it will retrieve reviewers, the ``Differential Revision``, etc from the review
|
||||
and place it in the commit message. You may also commit an accepted change
|
||||
directly using ``git llvm push``, per the section in the :ref:`getting started
|
||||
guide <commit_from_git>`.
|
||||
|
||||
Note that if you commit the change without using Arcanist and forget to add the
|
||||
``Differential Revision`` line to your commit message then it is recommended
|
||||
@ -174,24 +176,9 @@ that you close the review manually. In the web UI, under "Leap Into Action" put
|
||||
the SVN revision number in the Comment, set the Action to "Close Revision" and
|
||||
click Submit. Note the review must have been Accepted first.
|
||||
|
||||
Subversion and Arcanist
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
On a clean Subversion working copy run the following (where ``<Revision>`` is
|
||||
the Phabricator review number):
|
||||
|
||||
::
|
||||
|
||||
arc patch D<Revision>
|
||||
arc commit --revision D<Revision>
|
||||
|
||||
The first command will take the latest version of the reviewed patch and apply it to the working
|
||||
copy. The second command will commit this revision to trunk.
|
||||
|
||||
git-svn and Arcanist
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This presumes that the git repository has been configured as described in :ref:`developers-work-with-git-svn`.
|
||||
Committing someone's change from Phabricator
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
On a clean Git repository on an up to date ``master`` branch run the
|
||||
following (where ``<Revision>`` is the Phabricator review number):
|
||||
@ -205,17 +192,31 @@ This will create a new branch called ``arcpatch-D<Revision>`` based on the
|
||||
current ``master`` and will create a commit corresponding to ``D<Revision>`` with a
|
||||
commit message derived from information in the Phabricator review.
|
||||
|
||||
Check you are happy with the commit message and amend it if necessary. Now switch to
|
||||
the ``master`` branch and add the new commit to it and commit it to trunk. This
|
||||
can be done by running the following:
|
||||
Check you are happy with the commit message and amend it if necessary. Then,
|
||||
make sure the commit is up-to-date, and commit it. This can be done by running
|
||||
the following:
|
||||
|
||||
::
|
||||
|
||||
git checkout master
|
||||
git merge --ff-only arcpatch-D<Revision>
|
||||
git svn dcommit
|
||||
git pull --rebase origin master
|
||||
git show # Ensure the patch looks correct.
|
||||
ninja check-$whatever # Rerun the appropriate tests if needed.
|
||||
git llvm push
|
||||
|
||||
Subversion and Arcanist (deprecated)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To download a change from Phabricator and commit it with subversion, you should
|
||||
first make sure you have a clean working directory. Then run the following
|
||||
(where ``<Revision>`` is the Phabricator review number):
|
||||
|
||||
::
|
||||
|
||||
arc patch D<Revision>
|
||||
arc commit --revision D<Revision>
|
||||
|
||||
The first command will take the latest version of the reviewed patch and apply
|
||||
it to the working copy. The second command will commit this revision to trunk.
|
||||
|
||||
Abandoning a change
|
||||
-------------------
|
||||
@ -241,9 +242,9 @@ requests. We're looking into what the right long-term hosting for this is, but
|
||||
note that it is a derivative of an existing open source project, and so not
|
||||
trivially a good fit for an official LLVM project.
|
||||
|
||||
.. _LLVM's Phabricator: http://reviews.llvm.org
|
||||
.. _`http://reviews.llvm.org`: http://reviews.llvm.org
|
||||
.. _Code Repository Browser: http://reviews.llvm.org/diffusion/
|
||||
.. _LLVM's Phabricator: https://reviews.llvm.org
|
||||
.. _`https://reviews.llvm.org`: https://reviews.llvm.org
|
||||
.. _Code Repository Browser: https://reviews.llvm.org/diffusion/
|
||||
.. _Arcanist Quick Start: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/
|
||||
.. _Arcanist User Guide: https://secure.phabricator.com/book/phabricator/article/arcanist/
|
||||
.. _llvm-reviews GitHub project: https://github.com/r4nt/llvm-reviews/
|
||||
|
@ -223,4 +223,4 @@ efficiently to minimize the sizes of the underlying bitsets.
|
||||
ret void
|
||||
}
|
||||
|
||||
.. _GlobalLayoutBuilder: http://git.llvm.org/klaus/llvm/blob/master/include/llvm/Transforms/IPO/LowerTypeTests.h
|
||||
.. _GlobalLayoutBuilder: https://github.com/llvm/llvm-project/blob/master/llvm/include/llvm/Transforms/IPO/LowerTypeTests.h
|
||||
|
@ -374,7 +374,7 @@ Performance
|
||||
-----------
|
||||
|
||||
This section shows the execution time of Clang on a simple benchmark:
|
||||
`gcc-loops <http://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/>`_.
|
||||
`gcc-loops <https://github.com/llvm/llvm-test-suite/tree/master/SingleSource/UnitTests/Vectorizer>`_.
|
||||
This benchmarks is a collection of loops from the GCC autovectorization
|
||||
`page <http://gcc.gnu.org/projects/tree-ssa/vectorization.html>`_ by Dorit Nuzman.
|
||||
|
||||
|
@ -232,7 +232,7 @@ For developers of applications which use LLVM as a library.
|
||||
|
||||
`Documentation for Go bindings <http://godoc.org/llvm.org/llvm/bindings/go/llvm>`_
|
||||
|
||||
`ViewVC Repository Browser <http://llvm.org/viewvc/>`_
|
||||
`Github Source Repository Browser <http://github.com/llvm/llvm-project//>`_
|
||||
..
|
||||
|
||||
:doc:`CompilerWriterInfo`
|
||||
|
@ -4,7 +4,7 @@
|
||||
target datalayout = "e-m:e-i8:8:32-i16:16:32-i64:64-i128:128-n32:64-S128"
|
||||
|
||||
; This test is reduced from the matrix multiplication benchmark in the test-suite:
|
||||
; http://www.llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/Benchmarks/Misc/matmul_f64_4x4.c
|
||||
; https://github.com/llvm/llvm-test-suite/tree/master/SingleSource/Benchmarks/Misc/matmul_f64_4x4.c
|
||||
; The operations here are expected to be vectorized to <2 x double>.
|
||||
; Otherwise, performance will suffer on Cortex-A53.
|
||||
|
||||
|
@ -4,7 +4,7 @@
|
||||
target datalayout = "e-m:e-i8:8:32-i16:16:32-i64:64-i128:128-n32:64-S128"
|
||||
|
||||
; This test is reduced from the TSVC evaluation of vectorizers:
|
||||
; http://www.llvm.org/viewvc/llvm-project/test-suite/trunk/MultiSource/Benchmarks/TSVC/LoopRerolling-flt/tsc.c?view=log
|
||||
; https://github.com/llvm/llvm-test-suite/commits/master/MultiSource/Benchmarks/TSVC/LoopRerolling-flt/tsc.c
|
||||
; Two loads and an fmul are expected to be vectorized to <2 x float>.
|
||||
; Otherwise, performance will suffer on Cortex-A53.
|
||||
; See https://bugs.llvm.org/show_bug.cgi?id=36280 for more details.
|
||||
|
Loading…
x
Reference in New Issue
Block a user