llvm.org GIT mirror llvm / 8986b31
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 James Y Knight 9 months ago
8 changed file(s) with 249 addition(s) and 473 deletion(s). Raw diff Collapse all Expand all
2121
2222 #. Make life as simple and easy for contributors as possible.
2323
24 #. Keep the top of Subversion trees as stable as possible.
24 #. Keep the tip of tree as stable as possible.
2525
2626 #. Establish awareness of the project's :ref:`copyright, license, and patent
2727 policies ` with contributors to the project.
7979 When making a patch for review, the goal is to make it as easy for the reviewer
8080 to read it as possible. As such, we recommend that you:
8181
82 #. Make your patch against the Subversion trunk, not a branch, and not an old
83 version of LLVM. This makes it easy to apply the patch. For information on
84 how to check out SVN trunk, please see the `Getting Started
85 Guide `_.
82 #. Make your patch against git master, not a branch, and not an old version
83 of LLVM. This makes it easy to apply the patch. For information on how to
84 clone from git, please see the :ref:`Getting Started Guide
85 `.
8686
8787 #. Similarly, patches should be submitted soon after they are generated. Old
8888 patches may not apply correctly if the underlying code changes between the
8989 time the patch was created and the time it is applied.
9090
91 #. Patches should be made with ``svn diff``, or similar. If you use a
91 #. Patches should be made with ``git format-patch``, or similar. If you use a
9292 different tool, make sure it uses the ``diff -u`` format and that it
9393 doesn't contain clutter which makes it hard to read.
94
95 #. If you are modifying generated files, such as the top-level ``configure``
96 script, please separate out those changes into a separate patch from the rest
97 of your changes.
9894
9995 Once your patch is ready, submit it by emailing it to the appropriate project's
10096 commit mailing list (or commit it directly if applicable). Alternatively, some
186182 problem, we have a notion of an 'owner' for a piece of the code. The sole
187183 responsibility of a code owner is to ensure that a commit to their area of the
188184 code is appropriately reviewed, either by themself or by someone else. The list
189 of current code owners can be found in the file
190 `CODE_OWNERS.TXT `_
191 in the root of the LLVM source tree.
185 of current code owners can be found in the file `CODE_OWNERS.TXT
186 `_ in the
187 root of the LLVM source tree.
192188
193189 Note that code ownership is completely different than reviewers: anyone can
194190 review a piece of code, and we welcome code review from anyone who is
77 Overview
88 ========
99
10 Welcome to LLVM! In order to get started, you first need to know some basic
11 information.
12
13 First, LLVM comes in three pieces. The first piece is the LLVM suite. This
14 contains all of the tools, libraries, and header files needed to use LLVM. It
15 contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It
16 also contains basic regression tests that can be used to test the LLVM tools and
17 the Clang front end.
18
19 The second piece is the `Clang `_ front end. This
20 component compiles C, C++, Objective C, and Objective C++ code into LLVM
21 bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the
22 LLVM tools from the LLVM suite.
23
24 There is a third, optional piece called Test Suite. It is a suite of programs
25 with a testing harness that can be used to further test LLVM's functionality
26 and performance.
10 Welcome to the LLVM project! In order to get started, you first need to know
11 some basic information.
12
13 First, the LLVM project has multiple components. The core of the project is
14 itself called "LLVM". This contains all of the tools, libraries, and header
15 files needed to process an intermediate representation and convert it into
16 object files. It contains an assembler, disassembler, bitcode analyzer and
17 bitcode optimizer. It also contains basic regression tests.
18
19 Another piece is the `Clang `_ front end. This
20 component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode
21 -- and from there into object files, using LLVM.
22
23 There are other components as well:
24 the `libc++ C++ standard library `_,
25 the `LLD linker `_, and more.
2726
2827 Getting Started Quickly (A Summary)
2928 ===================================
3837 #. Read the documentation.
3938 #. Remember that you were warned twice about reading the documentation.
4039
41 * In particular, the *relative paths specified are important*.
42
43 #. Checkout LLVM:
44
45 * ``cd where-you-want-llvm-to-live``
46 * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
47
48 #. Checkout Clang:
49
50 * ``cd where-you-want-llvm-to-live``
51 * ``cd llvm/tools``
52 * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
53
54 #. Checkout Extra Clang Tools **[Optional]**:
55
56 * ``cd where-you-want-llvm-to-live``
57 * ``cd llvm/tools/clang/tools``
58 * ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
59
60 #. Checkout LLD linker **[Optional]**:
61
62 * ``cd where-you-want-llvm-to-live``
63 * ``cd llvm/tools``
64 * ``svn co http://llvm.org/svn/llvm-project/lld/trunk lld``
65
66 #. Checkout Polly Loop Optimizer **[Optional]**:
67
68 * ``cd where-you-want-llvm-to-live``
69 * ``cd llvm/tools``
70 * ``svn co http://llvm.org/svn/llvm-project/polly/trunk polly``
71
72 #. Checkout Compiler-RT (required to build the sanitizers) **[Optional]**:
73
74 * ``cd where-you-want-llvm-to-live``
75 * ``cd llvm/projects``
76 * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
77
78 #. Checkout Libomp (required for OpenMP support) **[Optional]**:
79
80 * ``cd where-you-want-llvm-to-live``
81 * ``cd llvm/projects``
82 * ``svn co http://llvm.org/svn/llvm-project/openmp/trunk openmp``
83
84 #. Checkout libcxx and libcxxabi **[Optional]**:
85
86 * ``cd where-you-want-llvm-to-live``
87 * ``cd llvm/projects``
88 * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
89 * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
90
91 #. Get the Test Suite Source Code **[Optional]**
92
93 * ``cd where-you-want-llvm-to-live``
94 * ``cd llvm/projects``
95 * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite``
96
97 #. Configure and build LLVM and Clang:
98
99 *Warning:* Make sure you've checked out *all of* the source code
100 before trying to configure with cmake. cmake does not pickup newly
101 added source directories in incremental builds.
102
103 The build uses `CMake `_. LLVM requires CMake 3.4.3 to build. It
104 is generally recommended to use a recent CMake, especially if you're
105 generating Ninja build files. This is because the CMake project is constantly
106 improving the quality of the generators, and the Ninja generator gets a lot
107 of attention.
108
109 * ``cd where you want to build llvm``
40 #. Checkout LLVM (including related subprojects like Clang):
41
42 * ``git clone https://github.com/llvm/llvm-project.git``
43 * Or, on windows, ``git clone --config core.autocrlf=false
44 https://github.com/llvm/llvm-project.git``
45
46 #. Configure and build LLVM and Clang:.
47
48 * ``cd llvm-project``
11049 * ``mkdir build``
11150 * ``cd build``
112 * ``cmake -G [options] ``
51 * ``cmake -G [options] ../llvm``
11352
11453 Some common generators are:
11554
116 * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
11755 * ``Ninja`` --- for generating `Ninja `_
11856 build files. Most llvm developers use Ninja.
57 * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
11958 * ``Visual Studio`` --- for generating Visual Studio projects and
12059 solutions.
12160 * ``Xcode`` --- for generating Xcode projects.
12261
12362 Some Common options:
12463
64 * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
65 subprojects you'd like to additionally build. Can include any of: clang,
66 libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld, polly, or
67 debuginfo-tests.
68
69 For example, to build LLVM, Clang, libcxx, and libcxxabi, use
70 ``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
71
12572 * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
12673 pathname of where you want the LLVM tools and libraries to be installed
12774 (default ``/usr/local``).
13481
13582 * Run your build tool of choice!
13683
137 * The default target (i.e. ``make``) will build all of LLVM
138
139 * The ``check-all`` target (i.e. ``make check-all``) will run the
84 * The default target (i.e. ``ninja`` or ``make``) will build all of LLVM.
85
86 * The ``check-all`` target (i.e. ``ninja check-all``) will run the
14087 regression tests to ensure everything is in working order.
14188
14289 * CMake will generate build targets for each tool and library, and most
14390 LLVM sub-projects generate their own ``check-`` target.
14491
145 * Running a serial build will be *slow*. Make sure you run a
146 parallel build; for ``make``, use ``make -j``.
92 * Running a serial build will be *slow*. Make sure you run a parallel
93 build. That's already done by default in Ninja; for ``make``, use
94 ``make -j NNN`` (with an appropriate value of NNN, e.g. number of CPUs
95 you have.)
14796
14897 * For more information see `CMake `_
14998
171120 ================== ===================== =============
172121 Linux x86\ :sup:`1` GCC, Clang
173122 Linux amd64 GCC, Clang
174 Linux ARM\ :sup:`4` GCC, Clang
123 Linux ARM GCC, Clang
175124 Linux PowerPC GCC, Clang
176125 Solaris V9 (Ultrasparc) GCC
177126 FreeBSD x86\ :sup:`1` GCC, Clang
191140 #. Code generation supported for 32-bit ABI only
192141 #. To use LLVM modules on Win32-based system, you may configure LLVM
193142 with ``-DBUILD_SHARED_LIBS=On``.
194 #. MCJIT not working well pre-v7, old JIT engine not supported any more.
195143
196144 Note that Debug builds require a lot of time and disk space. An LLVM-only build
197145 will need about 1-3 GB of space. A full build of LLVM and Clang will need around
432380 ---------------------------
433381
434382 If you have the LLVM distribution, you will need to unpack it before you can
435 begin to compile it. LLVM is distributed as a set of two files: the LLVM suite
436 and the LLVM GCC front end compiled for your platform. There is an additional
437 test suite that is optional. Each file is a TAR archive that is compressed with
438 the gzip program.
383 begin to compile it. LLVM is distributed as a number of different
384 subprojects. Each one has its own download which is a TAR archive that is
385 compressed with the gzip program.
439386
440387 The files are as follows, with *x.y* marking the version number:
441388
443390
444391 Source release for the LLVM libraries and tools.
445392
446 ``llvm-test-x.y.tar.gz``
447
448 Source release for the LLVM test-suite.
393 ``cfe-x.y.tar.gz``
394
395 Source release for the Clang frontend.
449396
450397 .. _checkout:
451398
452 Checkout LLVM from Subversion
453 -----------------------------
454
455 If you have access to our Subversion repository, you can get a fresh copy of the
456 entire source code. All you need to do is check it out from Subversion as
457 follows:
399 Checkout LLVM from Git
400 ----------------------
401
402 You can also checkout the source code for LLVM from Git. While the LLVM
403 project's official source-code repository is Subversion, we are in the process
404 of migrating to git. We currently recommend that all developers use Git for
405 day-to-day development.
406
407 .. note::
408
409 Passing ``--config core.autocrlf=false`` should not be required in
410 the future after we adjust the .gitattribute settings correctly, but
411 is required for Windows users at the time of this writing.
412
413 Simply run:
414
415 .. code-block:: console
416
417 % git clone https://github.com/llvm/llvm-project.git`
418
419 or on Windows,
420
421 .. code-block:: console
422
423 % git clone --config core.autocrlf=false https://github.com/llvm/llvm-project.git
424
425 This will create an '``llvm-project``' directory in the current directory and
426 fully populate it with all of the source code, test directories, and local
427 copies of documentation files for LLVM and all the related subprojects. Note
428 that unlike the tarballs, which contain each subproject in a separate file, the
429 git repository contains all of the projects together.
430
431 If you want to get a specific release (as opposed to the most recent revision),
432 you can check out a tag after cloning the repository. E.g., `git checkout
433 llvmorg-6.0.1` inside the ``llvm-project`` directory created by the above
434 command. Use `git tag -l` to list all of them.
435
436 Sending patches
437 ^^^^^^^^^^^^^^^
438
439 Please read `Developer Policy `_, too.
440
441 We don't currently accept github pull requests, so you'll need to send patches
442 either via emailing to llvm-commits, or, preferably, via :ref:`Phabricator
443 `.
444
445 You'll generally want to make sure your branch has a single commit,
446 corresponding to the review you wish to send, up-to-date with the upstream
447 ``origin/master`` branch, and doesn't contain merges. Once you have that, you
448 can use ``git show`` or ``git format-patch`` to output the diff, and attach it
449 to a Phabricator review (or to an email message).
450
451 However, using the "Arcanist" tool is often easier. After `installing
452 arcanist`_, you can upload the latest commit using:
453
454 .. code-block:: console
455
456 % arc diff HEAD~1
457
458 Additionally, before sending a patch for review, please also try to ensure it's
459 formatted properly. We use ``clang-format`` for this, which has git integration
460 through the ``git-clang-format`` script. On some systems, it may already be
461 installed (or be installable via your package manager). If so, you can simply
462 run it -- the following command will format only the code changed in the most
463 recent commit:
464
465 .. code-block:: console
466
467 % git clang-format HEAD~1
468
469 Note that this modifies the files, but doesn't commit them -- you'll likely want
470 to run
471
472 .. code-block:: console
473
474 % git commit --amend -a
475
476 in order to update the last commit with all pending changes.
477
478 .. note::
479 If you don't already have ``clang-format`` or ``git clang-format`` installed
480 on your system, the ``clang-format`` binary will be built alongside clang, and
481 the git integration can be run from
482 ``clang/tools/clang-format/git-clang-format``.
483
484
485 .. _commit_from_git:
486
487 For developers to commit changes from Git
488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
489
490 A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it
491 to your path, you can push committed changes upstream with ``git llvm
492 push``. While this creates a Subversion checkout and patches it under the hood,
493 it does not require you to have interaction with it.
494
495 .. code-block:: console
496
497 % export PATH=$PATH:$TOP_LEVEL_DIR/llvm-project/llvm/utils/git-svn/
498 % git llvm push
499
500 Within a couple minutes after pushing to subversion, the svn commit will have
501 been converted back to a Git commit, and made its way into the official Git
502 repository. At that point, ``git pull`` should get back the changes as they were
503 committed.
504
505 You'll likely want to ``git pull --rebase`` to get the official git commit
506 downloaded back to your repository. The SVN revision numbers of each commit can
507 be found at the end of the commit message, e.g. ``llvm-svn: 350914``.
508
509 You may also find the ``-n`` flag useful, like ``git llvm push -n``. This runs
510 through all the steps of committing _without_ actually doing the commit, and
511 tell you what it would have done. That can be useful if you're unsure whether
512 the right thing will happen.
513
514 Checkout via SVN (deprecated)
515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
516
517 Until we have fully migrated to Git, you may also get a fresh copy of
518 the code from the official Subversion repository.
458519
459520 * ``cd where-you-want-llvm-to-live``
460521 * Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
474535 * Release 1.1 through 2.8: **RELEASE_11** and so on
475536 * Release 1.0: **RELEASE_1**
476537
477 If you would like to get the LLVM test suite (a separate package as of 1.4), you
478 get it from the Subversion repository:
479
480 .. code-block:: console
481
482 % cd llvm/projects
483 % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
484
485 By placing it in the ``llvm/projects``, it will be automatically configured by
486 the LLVM cmake configuration.
487
488 Git Mirror
489 ----------
490
491 Git mirrors are available for a number of LLVM subprojects. These mirrors sync
492 automatically with each Subversion commit and contain all necessary git-svn
493 marks (so, you can recreate git-svn metadata locally). Note that right now
494 mirrors reflect only ``trunk`` for each project.
495
496 .. note::
497
498 On Windows, first you will want to do ``git config --global core.autocrlf
499 false`` before you clone. This goes a long way toward ensuring that
500 line-endings will be handled correctly (the LLVM project mostly uses Linux
501 line-endings).
502
503 You can do the read-only Git clone of LLVM via:
504
505 .. code-block:: console
506
507 % git clone https://git.llvm.org/git/llvm.git/
508
509 If you want to check out clang too, run:
510
511 .. code-block:: console
512
513 % cd llvm/tools
514 % git clone https://git.llvm.org/git/clang.git/
515
516 If you want to check out compiler-rt (required to build the sanitizers), run:
517
518 .. code-block:: console
519
520 % cd llvm/projects
521 % git clone https://git.llvm.org/git/compiler-rt.git/
522
523 If you want to check out libomp (required for OpenMP support), run:
524
525 .. code-block:: console
526
527 % cd llvm/projects
528 % git clone https://git.llvm.org/git/openmp.git/
529
530 If you want to check out libcxx and libcxxabi (optional), run:
531
532 .. code-block:: console
533
534 % cd llvm/projects
535 % git clone https://git.llvm.org/git/libcxx.git/
536 % git clone https://git.llvm.org/git/libcxxabi.git/
537
538 If you want to check out the Test Suite Source Code (optional), run:
539
540 .. code-block:: console
541
542 % cd llvm/projects
543 % git clone https://git.llvm.org/git/test-suite.git/
544
545 Since the upstream repository is in Subversion, you should use ``git
546 pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history
547 in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the
548 master branch, run the following command:
549
550 .. code-block:: console
551
552 % git config branch.master.rebase true
553
554 Sending patches with Git
555 ^^^^^^^^^^^^^^^^^^^^^^^^
556
557 Please read `Developer Policy `_, too.
558
559 Assume ``master`` points the upstream and ``mybranch`` points your working
560 branch, and ``mybranch`` is rebased onto ``master``. At first you may check
561 sanity of whitespaces:
562
563 .. code-block:: console
564
565 % git diff --check master..mybranch
566
567 The easiest way to generate a patch is as below:
568
569 .. code-block:: console
570
571 % git diff master..mybranch > /path/to/mybranch.diff
572
573 It is a little different from svn-generated diff. git-diff-generated diff has
574 prefixes like ``a/`` and ``b/``. Don't worry, most developers might know it
575 could be accepted with ``patch -p1 -N``.
576
577 But you may generate patchset with git-format-patch. It generates by-each-commit
578 patchset. To generate patch files to attach to your article:
579
580 .. code-block:: console
581
582 % git format-patch --no-attach master..mybranch -o /path/to/your/patchset
583
584 If you would like to send patches directly, you may use git-send-email or
585 git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
586
587 .. code-block:: console
588
589 % git format-patch --attach master..mybranch --stdout | git imap-send
590
591 Then, your .git/config should have [imap] sections.
592
593 .. code-block:: ini
594
595 [imap]
596 host = imaps://imap.gmail.com
597 user = your.gmail.account@gmail.com
598 pass = himitsu!
599 port = 993
600 sslverify = false
601 ; in English
602 folder = "[Gmail]/Drafts"
603 ; example for Japanese, "Modified UTF-7" encoded.
604 folder = "[Gmail]/&Tgtm+DBN-"
605 ; example for Traditional Chinese
606 folder = "[Gmail]/&g0l6Pw-"
607
608 .. _developers-work-with-git-svn:
609
610 For developers to work with git-svn
611 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
612
613 To set up clone from which you can submit code using ``git-svn``, run:
614
615 .. code-block:: console
616
617 % git clone https://git.llvm.org/git/llvm.git/
618 % cd llvm
619 % git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=
620 % git config svn-remote.svn.fetch :refs/remotes/origin/master
621 % git svn rebase -l # -l avoids fetching ahead of the git mirror.
622
623 # If you have clang too:
624 % cd tools
625 % git clone https://git.llvm.org/git/clang.git/
626 % cd clang
627 % git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=
628 % git config svn-remote.svn.fetch :refs/remotes/origin/master
629 % git svn rebase -l
630
631 Likewise for compiler-rt, libomp and test-suite.
632
633 To update this clone without generating git-svn tags that conflict with the
634 upstream Git repo, run:
635
636 .. code-block:: console
637
638 % git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees.
639 % git checkout master
640 % git svn rebase -l
641 % (cd tools/clang &&
642 git checkout master &&
643 git svn rebase -l)
644
645 Likewise for compiler-rt, libomp and test-suite.
646
647 This leaves your working directories on their master branches, so you'll need to
648 ``checkout`` each working branch individually and ``rebase`` it on top of its
649 parent branch.
650
651 For those who wish to be able to update an llvm repo/revert patches easily using
652 git-svn, please look in the directory for the scripts ``git-svnup`` and
653 ``git-svnrevert``.
654
655 To perform the aforementioned update steps go into your source directory and
656 just type ``git-svnup`` or ``git svnup`` and everything will just work.
657
658 If one wishes to revert a commit with git-svn, but do not want the git hash to
659 escape into the commit message, one can use the script ``git-svnrevert`` or
660 ``git svnrevert`` which will take in the git hash for the commit you want to
661 revert, look up the appropriate svn revision, and output a message where all
662 references to the git hash have been replaced with the svn revision.
663
664 To commit back changes via git-svn, use ``git svn dcommit``:
665
666 .. code-block:: console
667
668 % git svn dcommit
669
670 Note that git-svn will create one SVN commit for each Git commit you have pending,
671 so squash and edit each commit before executing ``dcommit`` to make sure they all
672 conform to the coding standards and the developers' policy.
673
674 On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict,
675 please make sure your current branch is up-to-date (via fetch/rebase) before
676 proceeding.
677
678 The git-svn metadata can get out of sync after you mess around with branches and
679 ``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining
680 about files with uncommitted changes. The fix is to rebuild the metadata:
681
682 .. code-block:: console
683
684 % rm -rf .git/svn
685 % git svn rebase -l
686
687 Please, refer to the Git-SVN manual (``man git-svn``) for more information.
688
689 For developers to work with a git monorepo
690 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
691
692 .. note::
693
694 This set-up is using an unofficial mirror hosted on GitHub, use with caution.
695
696 To set up a clone of all the llvm projects using a unified repository:
697
698 .. code-block:: console
699
700 % export TOP_LEVEL_DIR=`pwd`
701 % git clone https://github.com/llvm-project/llvm-project-20170507/ llvm-project
702 % cd llvm-project
703 % git config branch.master.rebase true
704
705 You can configure various build directory from this clone, starting with a build
706 of LLVM alone:
707
708 .. code-block:: console
709
710 % cd $TOP_LEVEL_DIR
711 % mkdir llvm-build && cd llvm-build
712 % cmake -GNinja ../llvm-project/llvm
713
714 Or lldb:
715
716 .. code-block:: console
717
718 % cd $TOP_LEVEL_DIR
719 % mkdir lldb-build && cd lldb-build
720 % cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS=lldb
721
722 Or a combination of multiple projects:
723
724 .. code-block:: console
725
726 % cd $TOP_LEVEL_DIR
727 % mkdir clang-build && cd clang-build
728 % cmake -GNinja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"
729
730 A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it
731 to your path, you can push committed changes upstream with ``git llvm push``.
732
733 .. code-block:: console
734
735 % export PATH=$PATH:$TOP_LEVEL_DIR/llvm-project/llvm/utils/git-svn/
736 % git llvm push
737
738 While this is using SVN under the hood, it does not require any interaction from
739 you with git-svn.
740 After a few minutes, ``git pull`` should get back the changes as they were
741 committed. Note that a current limitation is that ``git`` does not directly
742 record file rename, and thus it is propagated to SVN as a combination of
743 delete-add instead of a file rename.
744
745 The SVN revision of each monorepo commit can be found in the commit notes. git
746 does not fetch notes by default. The following commands will fetch the notes and
747 configure git to fetch future notes. Use ``git notes show $commit`` to look up
748 the SVN revision of a git commit. The notes show up ``git log``, and searching
749 the log is currently the recommended way to look up the git commit for a given
750 SVN revision.
751
752 .. code-block:: console
753
754 % git config --add remote.origin.fetch +refs/notes/commits:refs/notes/commits
755 % git fetch
756
757 If you are using `arc` to interact with Phabricator, you need to manually put it
758 at the root of the checkout:
759
760 .. code-block:: console
761
762 % cd $TOP_LEVEL_DIR
763 % cp llvm/.arcconfig ./
764 % mkdir -p .git/info/
765 % echo .arcconfig >> .git/info/exclude
766
767
768538 Local LLVM Configuration
769539 ------------------------
770540
771 Once checked out from the Subversion repository, the LLVM suite source code must
772 be configured before being built. This process uses CMake.
773 Unlinke the normal ``configure`` script, CMake
774 generates the build files in whatever format you request as well as various
775 ``*.inc`` files, and ``llvm/include/Config/config.h``.
541 Once checked out repository, the LLVM suite source code must be configured
542 before being built. This process uses CMake. Unlinke the normal ``configure``
543 script, CMake generates the build files in whatever format you request as well
544 as various ``*.inc`` files, and ``llvm/include/Config/config.h``.
776545
777546 Variables are passed to ``cmake`` on the command line using the format
778547 ``-D=``. The following variables are some common options
796565 | | running the install action of the build files. |
797566 +-------------------------+----------------------------------------------------+
798567 | LLVM_TARGETS_TO_BUILD | A semicolon delimited list controlling which |
799 | | targets will be built and linked into llc. This is |
800 | | equivalent to the ``--enable-targets`` option in |
801 | | the configure script. The default list is defined |
802 | | as ``LLVM_ALL_TARGETS``, and can be set to include |
568 | | targets will be built and linked into llvm. |
569 | | The default list is defined as |
570 | | ``LLVM_ALL_TARGETS``, and can be set to include |
803571 | | out-of-tree targets. The default value includes: |
804572 | | ``AArch64, AMDGPU, ARM, BPF, Hexagon, Mips, |
805573 | | MSP430, NVPTX, PowerPC, Sparc, SystemZ, X86, |
806574 | | XCore``. |
575 | | |
807576 +-------------------------+----------------------------------------------------+
808577 | LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source |
809578 | | code This is disabled by default because it is |
810579 | | slow and generates a lot of output. |
580 +-------------------------+----------------------------------------------------+
581 | LLVM_ENABLE_PROJECTS | A semicolon-delimited list selecting which of the |
582 | | other LLVM subprojects to additionally build. (Only|
583 | | effective when using a side-by-side project layout |
584 | | e.g. via git). The default list is empty. Can |
585 | | include: clang, libcxx, libcxxabi, libunwind, lldb,|
586 | | compiler-rt, lld, polly, or debuginfo-tests. |
811587 +-------------------------+----------------------------------------------------+
812588 | LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source |
813589 | | code. This is disabled by default because it is |
1029805
1030806 ``llvm/include/llvm/Config``
1031807
1032 Header files configured by the ``configure`` script.
1033 They wrap "standard" UNIX and C header files. Source code can include these
1034 header files which automatically take care of the conditional #includes that
1035 the ``configure`` script generates.
808 Header files configured by ``cmake``. They wrap "standard" UNIX and
809 C header files. Source code can include these header files which
810 automatically take care of the conditional #includes that ``cmake``
811 generates.
1036812
1037813 ``llvm/lib``
1038814 ------------
1104880 ``test-suite``
1105881 --------------
1106882
1107 A comprehensive correctness, performance, and benchmarking test suite for LLVM.
1108 Comes in a separate Subversion module because not every LLVM user is interested
1109 in such a comprehensive suite. For details see the :doc:`Testing Guide
1110 ` document.
883 A comprehensive correctness, performance, and benchmarking test suite
884 for LLVM. This comes in a ``separate git repository
885 ``, because it contains a
886 large amount of third-party code under a variety of licenses. For
887 details see the :doc:`Testing Guide ` document.
1111888
1112889 .. _tools:
1113890
13211098 * `LLVM Homepage `_
13221099 * `LLVM Doxygen Tree `_
13231100 * `Starting a Project that Uses LLVM `_
1101
1102 .. _installing arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/
0 .. _phabricator-reviews:
1
2 =============================
13 Code Reviews with Phabricator
24 =============================
1517 Sign up
1618 -------
1719
18 To get started with Phabricator, navigate to `http://reviews.llvm.org`_ and
20 To get started with Phabricator, navigate to `https://reviews.llvm.org`_ and
1921 click the power icon in the top right. You can register with a GitHub account,
2022 a Google account, or you can create your own profile.
2123
150152 Differential Revision:
151153
152154 where ```` is the URL for the code review, starting with
153 ``http://reviews.llvm.org/``.
155 ``https://reviews.llvm.org/``.
154156
155157 This allows people reading the version history to see the review for
156158 context. This also allows Phabricator to detect the commit, close the
161163 ``Differential Revision`` line (as the last line) to the commit message
162164 yourself.
163165
164 Using the Arcanist tool can simplify the process of committing reviewed code
165 as it will retrieve reviewers, the ``Differential Revision``, etc from the review
166 and place it in the commit message. Several methods of using Arcanist to commit
167 code are given below. If you do not wish to use Arcanist then simply commit
168 the reviewed patch as you would normally.
166 Using the Arcanist tool can simplify the process of committing reviewed code as
167 it will retrieve reviewers, the ``Differential Revision``, etc from the review
168 and place it in the commit message. You may also commit an accepted change
169 directly using ``git llvm push``, per the section in the :ref:`getting started
170 guide `.
169171
170172 Note that if you commit the change without using Arcanist and forget to add the
171173 ``Differential Revision`` line to your commit message then it is recommended
173175 the SVN revision number in the Comment, set the Action to "Close Revision" and
174176 click Submit. Note the review must have been Accepted first.
175177
176 Subversion and Arcanist
177 ^^^^^^^^^^^^^^^^^^^^^^^
178
179 On a clean Subversion working copy run the following (where ```` is
180 the Phabricator review number):
181
182 ::
183
184 arc patch D
185 arc commit --revision D
186
187 The first command will take the latest version of the reviewed patch and apply it to the working
188 copy. The second command will commit this revision to trunk.
189
190 git-svn and Arcanist
191 ^^^^^^^^^^^^^^^^^^^^
192
193 This presumes that the git repository has been configured as described in :ref:`developers-work-with-git-svn`.
178
179 Committing someone's change from Phabricator
180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194181
195182 On a clean Git repository on an up to date ``master`` branch run the
196183 following (where ```` is the Phabricator review number):
204191 current ``master`` and will create a commit corresponding to ``D`` with a
205192 commit message derived from information in the Phabricator review.
206193
207 Check you are happy with the commit message and amend it if necessary. Now switch to
208 the ``master`` branch and add the new commit to it and commit it to trunk. This
209 can be done by running the following:
210
211 ::
212
213 git checkout master
214 git merge --ff-only arcpatch-D
215 git svn dcommit
216
217
194 Check you are happy with the commit message and amend it if necessary. Then,
195 make sure the commit is up-to-date, and commit it. This can be done by running
196 the following:
197
198 ::
199
200 git pull --rebase origin master
201 git show # Ensure the patch looks correct.
202 ninja check-$whatever # Rerun the appropriate tests if needed.
203 git llvm push
204
205 Subversion and Arcanist (deprecated)
206 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
207
208 To download a change from Phabricator and commit it with subversion, you should
209 first make sure you have a clean working directory. Then run the following
210 (where ```` is the Phabricator review number):
211
212 ::
213
214 arc patch D
215 arc commit --revision D
216
217 The first command will take the latest version of the reviewed patch and apply
218 it to the working copy. The second command will commit this revision to trunk.
218219
219220 Abandoning a change
220221 -------------------
240241 note that it is a derivative of an existing open source project, and so not
241242 trivially a good fit for an official LLVM project.
242243
243 .. _LLVM's Phabricator: http://reviews.llvm.org
244 .. _`http://reviews.llvm.org`: http://reviews.llvm.org
245 .. _Code Repository Browser: http://reviews.llvm.org/diffusion/
244 .. _LLVM's Phabricator: https://reviews.llvm.org
245 .. _`https://reviews.llvm.org`: https://reviews.llvm.org
246 .. _Code Repository Browser: https://reviews.llvm.org/diffusion/
246247 .. _Arcanist Quick Start: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/
247248 .. _Arcanist User Guide: https://secure.phabricator.com/book/phabricator/article/arcanist/
248249 .. _llvm-reviews GitHub project: https://github.com/r4nt/llvm-reviews/
222222 ret void
223223 }
224224
225 .. _GlobalLayoutBuilder: http://git.llvm.org/klaus/llvm/blob/master/include/llvm/Transforms/IPO/LowerTypeTests.h
225 .. _GlobalLayoutBuilder: https://github.com/llvm/llvm-project/blob/master/llvm/include/llvm/Transforms/IPO/LowerTypeTests.h
373373 -----------
374374
375375 This section shows the execution time of Clang on a simple benchmark:
376 `gcc-loops ://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/>`_.
376 `gcc-loops s://github.com/llvm/llvm-test-suite/tree/master/SingleSource/UnitTests/Vectorizer>`_.
377377 This benchmarks is a collection of loops from the GCC autovectorization
378378 `page `_ by Dorit Nuzman.
379379
231231
232232 `Documentation for Go bindings `_
233233
234 `ViewVC Repository Browser />`_
234 `Github Source Repository Browser />`_
235235 ..
236236
237237 :doc:`CompilerWriterInfo`
33 target datalayout = "e-m:e-i8:8:32-i16:16:32-i64:64-i128:128-n32:64-S128"
44
55 ; This test is reduced from the matrix multiplication benchmark in the test-suite:
6 ; http://www.llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/Benchmarks/Misc/matmul_f64_4x4.c
6 ; https://github.com/llvm/llvm-test-suite/tree/master/SingleSource/Benchmarks/Misc/matmul_f64_4x4.c
77 ; The operations here are expected to be vectorized to <2 x double>.
88 ; Otherwise, performance will suffer on Cortex-A53.
99
33 target datalayout = "e-m:e-i8:8:32-i16:16:32-i64:64-i128:128-n32:64-S128"
44
55 ; This test is reduced from the TSVC evaluation of vectorizers:
6 ; http://www.llvm.org/viewvc/llvm-project/test-suite/trunk/MultiSource/Benchmarks/TSVC/LoopRerolling-flt/tsc.c?view=log
6 ; https://github.com/llvm/llvm-test-suite/commits/master/MultiSource/Benchmarks/TSVC/LoopRerolling-flt/tsc.c
77 ; Two loads and an fmul are expected to be vectorized to <2 x float>.
88 ; Otherwise, performance will suffer on Cortex-A53.
99 ; See https://bugs.llvm.org/show_bug.cgi?id=36280 for more details.