Index: llvm/trunk/docs/DeveloperPolicy.rst =================================================================== --- llvm/trunk/docs/DeveloperPolicy.rst +++ llvm/trunk/docs/DeveloperPolicy.rst @@ -22,7 +22,7 @@ #. 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 ` with contributors to the project. @@ -80,23 +80,19 @@ 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 `_. +#. 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 + `. #. 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 @@ 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 `_ -in the root of the LLVM source tree. +of current code owners can be found in the file `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 Index: llvm/trunk/docs/GettingStarted.rst =================================================================== --- llvm/trunk/docs/GettingStarted.rst +++ llvm/trunk/docs/GettingStarted.rst @@ -8,23 +8,22 @@ 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. - -The second piece is the `Clang `_ 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. - -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. +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. + +Another piece is the `Clang `_ 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 are other components as well: +the `libc++ C++ standard library `_, +the `LLD linker `_, and more. Getting Started Quickly (A Summary) =================================== @@ -39,90 +38,38 @@ #. 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 `_. 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 [options] `` + * ``cmake -G [options] ../llvm`` Some common generators are: - * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles. * ``Ninja`` --- for generating `Ninja `_ 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 @@ * 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-`` 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 `_ @@ -172,7 +121,7 @@ ================== ===================== ============= 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 @@ #. 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 @@ --------------------------- 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,336 +391,158 @@ 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 ------------------------------ - -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: +Checkout LLVM from Git +---------------------- -* ``cd where-you-want-llvm-to-live`` -* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` -* Read-Write: ``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` - -This will create an '``llvm``' directory in the current directory and fully -populate it with the LLVM source code, Makefiles, test directories, and local -copies of documentation files. - -If you want to get a specific release (as opposed to the most recent revision), -you can check it out from the '``tags``' directory (instead of '``trunk``'). The -following releases are located in the following subdirectories of the '``tags``' -directory: - -* Release 3.5.0 and later: **RELEASE_350/final** and so on -* Release 2.9 through 3.4: **RELEASE_29/final** and so on -* 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. +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:: - 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/ + 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. -If you want to check out libcxx and libcxxabi (optional), run: +Simply 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/ + % git clone https://github.com/llvm/llvm-project.git` -If you want to check out the Test Suite Source Code (optional), run: +or on Windows, .. 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: + % git clone --config core.autocrlf=false https://github.com/llvm/llvm-project.git -.. code-block:: console +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. - % git config branch.master.rebase true +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 with Git -^^^^^^^^^^^^^^^^^^^^^^^^ +Sending patches +^^^^^^^^^^^^^^^ Please read `Developer Policy `_, 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 +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 +`. -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]. +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). -.. 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= - % 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= - % 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: +However, using the "Arcanist" tool is often easier. After `installing +arcanist`_, you can upload the latest commit using: .. 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. + % arc diff HEAD~1 -To commit back changes via git-svn, use ``git svn dcommit``: +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 svn dcommit + % git clang-format HEAD~1 -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: +Note that this modifies the files, but doesn't commit them -- you'll likely want +to run .. code-block:: console - % rm -rf .git/svn - % git svn rebase -l + % git commit --amend -a -Please, refer to the Git-SVN manual (``man git-svn``) for more information. - -For developers to work with a git monorepo -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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``. - 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: +.. _commit_from_git: -.. 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" +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``. +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 -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. +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. -.. code-block:: console +Checkout via SVN (deprecated) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - % git config --add remote.origin.fetch +refs/notes/commits:refs/notes/commits - % git fetch +Until we have fully migrated to Git, you may also get a fresh copy of +the code from the official Subversion repository. -If you are using `arc` to interact with Phabricator, you need to manually put it -at the root of the checkout: +* ``cd where-you-want-llvm-to-live`` +* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` +* Read-Write: ``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` -.. code-block:: console +This will create an '``llvm``' directory in the current directory and fully +populate it with the LLVM source code, Makefiles, test directories, and local +copies of documentation files. - % cd $TOP_LEVEL_DIR - % cp llvm/.arcconfig ./ - % mkdir -p .git/info/ - % echo .arcconfig >> .git/info/exclude +If you want to get a specific release (as opposed to the most recent revision), +you can check it out from the '``tags``' directory (instead of '``trunk``'). The +following releases are located in the following subdirectories of the '``tags``' +directory: +* Release 3.5.0 and later: **RELEASE_350/final** and so on +* Release 2.9 through 3.4: **RELEASE_29/final** and so on +* Release 1.1 through 2.8: **RELEASE_11** and so on +* Release 1.0: **RELEASE_1** 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=``. The following variables are some common options @@ -797,19 +566,26 @@ | | 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 @@ ``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 @@ ``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 -` document. +A comprehensive correctness, performance, and benchmarking test suite +for LLVM. This comes in a ``separate git repository +``, because it contains a +large amount of third-party code under a variety of licenses. For +details see the :doc:`Testing Guide ` document. .. _tools: @@ -1322,3 +1099,5 @@ * `LLVM Homepage `_ * `LLVM Doxygen Tree `_ * `Starting a Project that Uses LLVM `_ + +.. _installing arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/ Index: llvm/trunk/docs/Phabricator.rst =================================================================== --- llvm/trunk/docs/Phabricator.rst +++ llvm/trunk/docs/Phabricator.rst @@ -1,3 +1,5 @@ +.. _phabricator-reviews: + ============================= Code Reviews with Phabricator ============================= @@ -16,7 +18,7 @@ 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 @@ Differential Revision: where ```` 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 @@ ``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 `. 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 @@ 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 ```` is -the Phabricator review number): - -:: - - arc patch D - arc commit --revision D -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 ```` is the Phabricator review number): @@ -205,17 +192,31 @@ current ``master`` and will create a commit corresponding to ``D`` 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 - 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 ```` is the Phabricator review number): + +:: + arc patch D + arc commit --revision D +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 @@ 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/ Index: llvm/trunk/docs/TypeMetadata.rst =================================================================== --- llvm/trunk/docs/TypeMetadata.rst +++ llvm/trunk/docs/TypeMetadata.rst @@ -223,4 +223,4 @@ 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 Index: llvm/trunk/docs/Vectorizers.rst =================================================================== --- llvm/trunk/docs/Vectorizers.rst +++ llvm/trunk/docs/Vectorizers.rst @@ -374,7 +374,7 @@ ----------- This section shows the execution time of Clang on a simple benchmark: -`gcc-loops `_. +`gcc-loops `_. This benchmarks is a collection of loops from the GCC autovectorization `page `_ by Dorit Nuzman. Index: llvm/trunk/docs/index.rst =================================================================== --- llvm/trunk/docs/index.rst +++ llvm/trunk/docs/index.rst @@ -232,7 +232,7 @@ `Documentation for Go bindings `_ -`ViewVC Repository Browser `_ +`Github Source Repository Browser `_ .. :doc:`CompilerWriterInfo` Index: llvm/trunk/test/Transforms/SLPVectorizer/AArch64/matmul.ll =================================================================== --- llvm/trunk/test/Transforms/SLPVectorizer/AArch64/matmul.ll +++ llvm/trunk/test/Transforms/SLPVectorizer/AArch64/matmul.ll @@ -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. Index: llvm/trunk/test/Transforms/SLPVectorizer/AArch64/tsc-s352.ll =================================================================== --- llvm/trunk/test/Transforms/SLPVectorizer/AArch64/tsc-s352.ll +++ llvm/trunk/test/Transforms/SLPVectorizer/AArch64/tsc-s352.ll @@ -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.