├── .gitignore ├── hello.c ├── images ├── test.c.013t.cfg.dot-in-xdot.png ├── test.c.021t.ssa.dot-in-xdot.png ├── grayed-out-assignee.bugzilla.png ├── test.c.237r.expand.dot-in-xdot.png ├── sourceware-login-assignee.bugzilla.png ├── test.c.235t.optimized.dot-in-xdot.png ├── test-with-loop.c.013t.cfg.dot-in-xdot.png └── test-with-loop.c.235t.optimized.dot-in-xdot.png ├── gcc-source-tree.rst ├── todo.rst ├── diving-into-gcc-internals.rst ├── .readthedocs.yaml ├── index.rst ├── memory-management.rst ├── readying-a-patch.rst ├── how-did-my-code-get-optimized.rst ├── make.bat ├── Makefile ├── getting-started.rst ├── looking-at-the-generated-asm.rst ├── gotchas-and-faq.rst ├── working-with-the-testsuite.rst ├── conf.py ├── how-to-improve-the-location-of-a-diagnostic.rst ├── debugging.rst ├── binaries-and-processes.rst ├── COPYING3 └── inside-cc1.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | *~ 3 | -------------------------------------------------------------------------------- /hello.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main (int argc, const char *argv[]) 4 | { 5 | printf ("Hello world\n"); 6 | return 0; 7 | } 8 | -------------------------------------------------------------------------------- /images/test.c.013t.cfg.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test.c.013t.cfg.dot-in-xdot.png -------------------------------------------------------------------------------- /images/test.c.021t.ssa.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test.c.021t.ssa.dot-in-xdot.png -------------------------------------------------------------------------------- /images/grayed-out-assignee.bugzilla.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/grayed-out-assignee.bugzilla.png -------------------------------------------------------------------------------- /images/test.c.237r.expand.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test.c.237r.expand.dot-in-xdot.png -------------------------------------------------------------------------------- /images/sourceware-login-assignee.bugzilla.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/sourceware-login-assignee.bugzilla.png -------------------------------------------------------------------------------- /images/test.c.235t.optimized.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test.c.235t.optimized.dot-in-xdot.png -------------------------------------------------------------------------------- /images/test-with-loop.c.013t.cfg.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test-with-loop.c.013t.cfg.dot-in-xdot.png -------------------------------------------------------------------------------- /images/test-with-loop.c.235t.optimized.dot-in-xdot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/davidmalcolm/gcc-newbies-guide/HEAD/images/test-with-loop.c.235t.optimized.dot-in-xdot.png -------------------------------------------------------------------------------- /gcc-source-tree.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2022-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | What's in the GCC source tree? 19 | ------------------------------ 20 | 21 | TODO 22 | -------------------------------------------------------------------------------- /todo.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | TODO 19 | ---- 20 | 21 | * "^L" 22 | 23 | * tree, gimple, RTL 24 | 25 | * global state 26 | 27 | Indices and tables 28 | ================== 29 | 30 | * :ref:`genindex` 31 | * :ref:`modindex` 32 | * :ref:`search` 33 | 34 | .. compare with: https://docs.python.org/devguide/ 35 | -------------------------------------------------------------------------------- /diving-into-gcc-internals.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2022-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Diving into GCC internals 19 | ========================= 20 | 21 | .. toctree:: 22 | :maxdepth: 1 23 | 24 | binaries-and-processes.rst 25 | looking-at-the-generated-asm.rst 26 | inside-cc1.rst 27 | how-did-my-code-get-optimized.rst 28 | gcc-source-tree.rst 29 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # Read the Docs configuration file for Sphinx projects 2 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 | 4 | # Required 5 | version: 2 6 | 7 | # Set the OS, Python version and other tools you might need 8 | build: 9 | os: ubuntu-22.04 10 | tools: 11 | python: "3.11" 12 | # You can also specify other tool versions: 13 | # nodejs: "20" 14 | # rust: "1.70" 15 | # golang: "1.20" 16 | 17 | # Build documentation in the "docs/" directory with Sphinx 18 | sphinx: 19 | configuration: conf.py 20 | # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs 21 | # builder: "dirhtml" 22 | # Fail on all warnings to avoid broken references 23 | # fail_on_warning: true 24 | 25 | # Optionally build your docs in additional formats such as PDF and ePub 26 | # formats: 27 | # - pdf 28 | # - epub 29 | 30 | # Optional but recommended, declare the Python requirements required 31 | # to build your documentation 32 | # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 33 | # python: 34 | # install: 35 | # - requirements: docs/requirements.txt 36 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | GCC for New Contributors 19 | ======================== 20 | 21 | This is an unofficial guide to GCC's internals, aimed at new developers, 22 | and at plugin authors. 23 | 24 | Source: https://github.com/davidmalcolm/gcc-newbies-guide 25 | 26 | I'm a relative newcomer to GCC, so I thought it was worth documenting 27 | some of the hurdles I ran into when I started working on GCC, to try 28 | to make it easier for others to start hacking on GCC. Hence this guide. 29 | 30 | Other sources of information: 31 | 32 | - The official "Contributing to GCC" guide on the GCC website: 33 | https://gcc.gnu.org/contribute.html 34 | 35 | - The official GCC "internals" guide is: 36 | https://gcc.gnu.org/onlinedocs/gccint/ 37 | 38 | - Another excellent resource is the material available at 39 | the website of the GCC Resource Center at IIT Bombay: 40 | https://www.cse.iitb.ac.in/grc/ 41 | 42 | - There is also much information on the GCC wiki: 43 | https://gcc.gnu.org/wiki/HomePage 44 | though sadly much of it is out-of-date - 45 | GCC is (at the time of writing) a 30-year-old project. 46 | 47 | Contents: 48 | 49 | .. toctree:: 50 | :maxdepth: 1 51 | 52 | diving-into-gcc-internals.rst 53 | gotchas-and-faq.rst 54 | getting-started.rst 55 | readying-a-patch.rst 56 | debugging.rst 57 | working-with-the-testsuite.rst 58 | how-to-improve-the-location-of-a-diagnostic.rst 59 | memory-management.rst 60 | todo.rst 61 | -------------------------------------------------------------------------------- /memory-management.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Memory Management in GCC 19 | ======================== 20 | 21 | We have a few different memory management strategies in GCC: 22 | 23 | * RAII types, which manage their own memory. An example 24 | is ``auto_vec``. 25 | 26 | * Heap allocation with manual deallocation, where you have 27 | to use the correct deallocator matching the allocator. 28 | (Sadly it's not always clear when looking at a pointer 29 | which allocator to use; it would be good to use wrapper 30 | classes to automate this). 31 | 32 | * ``new`` and ``delete`` 33 | 34 | * ``new[]`` and ``delete[]`` 35 | 36 | * ``malloc`` and ``free`` 37 | 38 | .. _ggc: 39 | 40 | * A garbage-collected heap: "ggc" (as opposed to "gcc"), 41 | with automatic deallocation. 42 | 43 | Data is allocated, and, when memory usage is high, a 44 | mark-and-sweep collector frees up no-longer used data. 45 | 46 | Various pointers and types in the source tree are tagged 47 | using the ``GTY`` preprocessor macro. This code is 48 | processed at build time using a custom tool, ``gengtype``. 49 | It locates garbage-collector "roots": global variables 50 | that can reference GC-allocated data - the roots of the 51 | mark-and-sweep operation. 52 | 53 | This pointer graph metadata is also used by our implementation 54 | of pre-compiled headers: a precompiled header is essentially 55 | just a snapshot of the GC-heap, which can be loaded back 56 | into memory, and the metadata is used to update all of 57 | the pointer cross-references within it. 58 | 59 | This means that anything that needs to be preserved in 60 | pre-compiled headers needs to be GC-allocated. 61 | 62 | Sadly, ``gengtype`` only supports a loosely-defined subset 63 | of C++ and can be fiddly to work with. 64 | Documentation can be seen at 65 | https://gcc.gnu.org/onlinedocs/gccint/Type-Information.html 66 | 67 | * obstacks: obstacks support a form of dynamic allocation 68 | in which various blocks of memory are allocated, and 69 | then are all released together. This is effectively a 70 | stack and thus fast, and only the "watermark" of the release 71 | point needs to be tracked. We use them a lot within 72 | optimization passes for allocating temporary data, releasing 73 | it in one go when we're done with a function. 74 | 75 | * :file:`alloc-pool.h` provides an optimized way of allocating 76 | chunks of known size 77 | 78 | Running gcc under valgrind 79 | ************************** 80 | See the notes on :ref:`invoking the compiler under valgrind `. 81 | -------------------------------------------------------------------------------- /readying-a-patch.rst: -------------------------------------------------------------------------------- 1 | Making a patch 2 | ============== 3 | 4 | Writing a patch is already something you can be proud of. 5 | However, so that your sweat was not spilled in vain, you'll want to 6 | submit it to the community for revision. 7 | 8 | Do not take this step lightly, as it might very well be the most tedious one. 9 | 10 | 11 | Indentation and formatting rules in a nutshell 12 | ############################################## 13 | 14 | If your patch isn't formatted according to our conventions, 15 | it will be returned to you so you can address it. 16 | Moreover GNU and GCC conventions were established in another century, 17 | when text editors were far less fancy. 18 | 19 | You may find the complete documentation on GCC coding conventions 20 | by checking `GNU standard `_ 21 | and the more specific `GCC style `_. 22 | 23 | Before submitting your patch to the mailing list gcc-patches@gcc.gnu.org, 24 | it is always good to run either `git gcc-verify` if your patch is the latest commit 25 | or manually with `contrib/check_GNU_style.sh`. 26 | 27 | WIP: Add vscode clang's configuration for GNU style. 28 | 29 | Regression testing + bootstrap = Regstrapping 30 | ############################################# 31 | 32 | To correctly test a patch, you may follow the procedure below 33 | 34 | First, make sure your control folder is "recent enough". 35 | Personally, I pull and regstrap my control once a week. 36 | 37 | To be done once a week: 38 | 39 | .. code-block:: bash 40 | 41 | cd /path/to/gcc-control 42 | # update your sources with the latest trunk 43 | cd sources 44 | git switch trunk 45 | git pull 46 | cd .. 47 | 48 | # Cleanup your build folder 49 | rm -r build && mkdir build 50 | cd build 51 | # configure WITHOUT disabling bootstrap. 52 | ../sources/configure --prefix=/path/to/gcc-control/install 53 | # Run the full testsuite. 54 | make -j16 bootstrap && make -k -j16 check 55 | 56 | Now that you have a fresh and up-to-date control, 57 | you will have a way to compare your patch and ensure 58 | you did not break anything i.e. introduced a regression. 59 | 60 | It may sounds obvious, but make sure your patch is 61 | branching off the same trunk as your control version's! 62 | 63 | .. code-block:: bash 64 | 65 | # find out your control's trunk 66 | cd /path/to/gcc-control/sources 67 | git show-ref -s refs/heads/trunk 68 | 69 | cd /path/to/gcc-patched/sources 70 | # check this matches the hash you got above 71 | # if not, do 72 | # git pull trunk 73 | git show-ref -s refs/heads/trunk 74 | git switch your/patch/branch 75 | # simplest way to see where your branch diverged from trunk 76 | git log 77 | # if your patch's branch branched earlier than your trunk's head, rebase 78 | git rebase trunk 79 | 80 | It might be best for you to ready your patch for trunk already, 81 | before regstrapping it. 82 | If you have a single patch, a single commit may suffice. 83 | It will anyway probably be your case as you debut with small patches. 84 | 85 | Therefore, if while working on your patch you created several commits, 86 | think about squashing them all into one. 87 | 88 | .. code-block::bash 89 | 90 | cd /path/to/gcc-patched/sources 91 | # N being the number of commits you want to squash together 92 | git rebase -i HEAD~N 93 | # in your editor, pick the first (top-most) commit, squash the others. 94 | # once done, save and exit, you will be asked to enter a new commit message. 95 | 96 | # If you didn't already have a proper commit message 97 | # generate one using the gcc-commit-mklog hook. 98 | git reset --soft HEAD^ 99 | git gcc-commit-mklog --signoff 100 | 101 | 102 | Once your done with preparing your commit, you can actually 103 | regstrap you patch and go make yourself a coffee. 104 | 105 | .. code-block:: bash 106 | 107 | cd /path/to/gcc-patched 108 | # Cleanup your build folder 109 | rm -r build && mkdir build 110 | cd build 111 | # configure WITHOUT disabling bootstrap. 112 | ../sources/configure --prefix=/path/to/gcc-patched/install 113 | # Run the full testsuite. 114 | make -j16 bootstrap && make -k -j16 check 115 | # Compare the result of your regstrap with control's 116 | # Be sure you understand the output. If you have a doubt, 117 | # better ask the mail list. 118 | ../sources/contrib/compare_tests /path/to/gcc-control/build . 119 | 120 | If everything went fine, then bravo! you can prepare your patch 121 | for the gcc-patches@gcc.gnu.org mail list. 122 | 123 | A few prior checks will save you some time though 124 | 125 | .. code-block:: bash 126 | 127 | cd /path/to/gcc-patched/sources 128 | mkdir -p ../patches 129 | # Format your patch for the mail list 130 | # This will append a git diff to your commit message 131 | git format-patch -o ../patches/ -1 132 | # Script helpful to spot some formatting issues in your code. 133 | contrib/check_GNU_style.sh ../patches/NAME_OF_YOUR_PATCH.patch 134 | # Check you commit's message includes a correct ChangeLog entry. 135 | contrib/gcc-changelog/git_check_commit.py HEAD^ 136 | 137 | If everything went as expected, you can submit your patch to the mail list. 138 | You may consider `git send-email` to do so and not break any formatting 139 | in the mail. 140 | -------------------------------------------------------------------------------- /how-did-my-code-get-optimized.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2024 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Exercise: What did the optimizer do? 19 | ==================================== 20 | 21 | A good exercise is to create some simple C code, let GCC optimize it, 22 | and figure out how the code got optimized. 23 | 24 | For example, consider: 25 | 26 | .. code-block:: c 27 | 28 | static int test (int a, int b, int c, int d) 29 | { 30 | if (a) 31 | return (b - c) * d; 32 | else 33 | return (c - b) * d; 34 | } 35 | 36 | static int simple_loop (int n, int a, int b, int c, int d) 37 | { 38 | int result; 39 | int i; 40 | for (i = 0; i < n; i++) 41 | result += test (a, b, c, d); 42 | return result; 43 | } 44 | 45 | int fn_with_constants (void) 46 | { 47 | return simple_loop (20, 1, 7, 4, 3); 48 | } 49 | 50 | If we run gcc on this: 51 | 52 | .. code-block:: sh 53 | 54 | gcc -S test-with-loop.c -O2 -fdump-tree-all-graph -fdump-ipa-all-graph -fdump-rtl-all-graph 55 | 56 | and look at the generated assembler 57 | 58 | :file:`test-with-loop.s`: 59 | 60 | .. code-block:: asm 61 | 62 | .file "test-with-loop.c" 63 | .text 64 | .p2align 4 65 | .globl fn_with_constants 66 | .type fn_with_constants, @function 67 | fn_with_constants: 68 | .LFB2: 69 | .cfi_startproc 70 | movl $180, %eax 71 | ret 72 | .cfi_endproc 73 | .LFE2: 74 | .size fn_with_constants, .-fn_with_constants 75 | .ident "GCC: (GNU) 10.3.1 20210422 (Red Hat 10.3.1-1)" 76 | .section .note.GNU-stack,"",@progbits 77 | 78 | 79 | we see that ``cc1`` has replaced all of our code with a simple ``return 180;`` 80 | 81 | The static functions have been optimized away. 82 | 83 | Try this with your own example. 84 | 85 | This is with GCC 10 on x86_64; your results may be different. 86 | 87 | At first glance this may seem like magic, but what is happening is that 88 | the various optimization passes simplify the code and these small 89 | simplifications build on each other, eventually leading to the trivial 90 | code seen above. 91 | 92 | How does it work? The way to track this down is to 93 | 94 | * follow the instructions on the previous page to dump the state 95 | of ``cc1`` at each of the various optimization passes. 96 | 97 | * do a binary search through the dump files to find the places where 98 | significant changes happen 99 | 100 | A good place to start is to look at the GIMPLE/RTL boundary, where 101 | ``optimized`` is the final state of the GIMPLE before it becomes RTL. 102 | For this example, we see that the optimization has already happened, 103 | using the GIMPLE IR: 104 | 105 | .. code-block:: c 106 | 107 | ;; Function fn_with_constants (fn_with_constants, funcdef_no=2, decl_uid=1948, cgraph_uid=3, symbol_order=2) 108 | 109 | fn_with_constants () 110 | { 111 | int result; 112 | 113 | [local count: 118111600]: 114 | result_6 = result_7(D) + 180; 115 | return result_6; 116 | 117 | } 118 | 119 | .. image:: images/test-with-loop.c.235t.optimized.dot-in-xdot.png 120 | 121 | Compare with the ``original`` (generic tree) representation compiing out 122 | of the C frontend: 123 | 124 | .. code-block:: c 125 | 126 | ;; Function test (null) 127 | ;; enabled by -tree-original 128 | 129 | 130 | { 131 | if (a != 0) 132 | { 133 | return (b - c) * d; 134 | } 135 | else 136 | { 137 | return (c - b) * d; 138 | } 139 | } 140 | 141 | 142 | ;; Function simple_loop (null) 143 | ;; enabled by -tree-original 144 | 145 | 146 | { 147 | int result; 148 | int i; 149 | 150 | int result; 151 | int i; 152 | i = 0; 153 | goto ; 154 | :; 155 | SAVE_EXPR ;, result = SAVE_EXPR + result;; 156 | i++ ; 157 | :; 158 | if (i < n) goto ; else goto ; 159 | :; 160 | return result; 161 | } 162 | 163 | 164 | ;; Function fn_with_constants (null) 165 | ;; enabled by -tree-original 166 | 167 | 168 | { 169 | return simple_loop (20, 1, 7, 4, 3); 170 | } 171 | 172 | and, once we have a CFG: 173 | 174 | .. image:: images/test-with-loop.c.013t.cfg.dot-in-xdot.png 175 | 176 | So the above optimizations are happening *somewhere* between ``cfg`` and 177 | ``optimized``. The exact details will vary from GCC release to release, and 178 | figuring it out is a useful exercise, so I'm leaving that to the reader. 179 | 180 | You'll want to do a binary search through the dumps. Note that in many of the 181 | dumps nothing much changes (e.g. the exception-handling pass is unliktly to 182 | do anything to the IR if there are no exceptions), whereas in a few passes, 183 | a lot changes, but exactly what those most useful passes are may vary 184 | depending on what your code is doing. 185 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=_build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . 10 | set I18NSPHINXOPTS=%SPHINXOPTS% . 11 | if NOT "%PAPER%" == "" ( 12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% 14 | ) 15 | 16 | if "%1" == "" goto help 17 | 18 | if "%1" == "help" ( 19 | :help 20 | echo.Please use `make ^` where ^ is one of 21 | echo. html to make standalone HTML files 22 | echo. dirhtml to make HTML files named index.html in directories 23 | echo. singlehtml to make a single large HTML file 24 | echo. pickle to make pickle files 25 | echo. json to make JSON files 26 | echo. htmlhelp to make HTML files and a HTML help project 27 | echo. qthelp to make HTML files and a qthelp project 28 | echo. devhelp to make HTML files and a Devhelp project 29 | echo. epub to make an epub 30 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 31 | echo. text to make text files 32 | echo. man to make manual pages 33 | echo. texinfo to make Texinfo files 34 | echo. gettext to make PO message catalogs 35 | echo. changes to make an overview over all changed/added/deprecated items 36 | echo. linkcheck to check all external links for integrity 37 | echo. doctest to run all doctests embedded in the documentation if enabled 38 | goto end 39 | ) 40 | 41 | if "%1" == "clean" ( 42 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 43 | del /q /s %BUILDDIR%\* 44 | goto end 45 | ) 46 | 47 | if "%1" == "html" ( 48 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html 49 | if errorlevel 1 exit /b 1 50 | echo. 51 | echo.Build finished. The HTML pages are in %BUILDDIR%/html. 52 | goto end 53 | ) 54 | 55 | if "%1" == "dirhtml" ( 56 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml 57 | if errorlevel 1 exit /b 1 58 | echo. 59 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. 60 | goto end 61 | ) 62 | 63 | if "%1" == "singlehtml" ( 64 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml 65 | if errorlevel 1 exit /b 1 66 | echo. 67 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. 68 | goto end 69 | ) 70 | 71 | if "%1" == "pickle" ( 72 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle 73 | if errorlevel 1 exit /b 1 74 | echo. 75 | echo.Build finished; now you can process the pickle files. 76 | goto end 77 | ) 78 | 79 | if "%1" == "json" ( 80 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json 81 | if errorlevel 1 exit /b 1 82 | echo. 83 | echo.Build finished; now you can process the JSON files. 84 | goto end 85 | ) 86 | 87 | if "%1" == "htmlhelp" ( 88 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp 89 | if errorlevel 1 exit /b 1 90 | echo. 91 | echo.Build finished; now you can run HTML Help Workshop with the ^ 92 | .hhp project file in %BUILDDIR%/htmlhelp. 93 | goto end 94 | ) 95 | 96 | if "%1" == "qthelp" ( 97 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp 98 | if errorlevel 1 exit /b 1 99 | echo. 100 | echo.Build finished; now you can run "qcollectiongenerator" with the ^ 101 | .qhcp project file in %BUILDDIR%/qthelp, like this: 102 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GCCContributorsGuide.qhcp 103 | echo.To view the help file: 104 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GCCContributorsGuide.ghc 105 | goto end 106 | ) 107 | 108 | if "%1" == "devhelp" ( 109 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp 110 | if errorlevel 1 exit /b 1 111 | echo. 112 | echo.Build finished. 113 | goto end 114 | ) 115 | 116 | if "%1" == "epub" ( 117 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub 118 | if errorlevel 1 exit /b 1 119 | echo. 120 | echo.Build finished. The epub file is in %BUILDDIR%/epub. 121 | goto end 122 | ) 123 | 124 | if "%1" == "latex" ( 125 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 126 | if errorlevel 1 exit /b 1 127 | echo. 128 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. 129 | goto end 130 | ) 131 | 132 | if "%1" == "text" ( 133 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text 134 | if errorlevel 1 exit /b 1 135 | echo. 136 | echo.Build finished. The text files are in %BUILDDIR%/text. 137 | goto end 138 | ) 139 | 140 | if "%1" == "man" ( 141 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man 142 | if errorlevel 1 exit /b 1 143 | echo. 144 | echo.Build finished. The manual pages are in %BUILDDIR%/man. 145 | goto end 146 | ) 147 | 148 | if "%1" == "texinfo" ( 149 | %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo 150 | if errorlevel 1 exit /b 1 151 | echo. 152 | echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. 153 | goto end 154 | ) 155 | 156 | if "%1" == "gettext" ( 157 | %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale 158 | if errorlevel 1 exit /b 1 159 | echo. 160 | echo.Build finished. The message catalogs are in %BUILDDIR%/locale. 161 | goto end 162 | ) 163 | 164 | if "%1" == "changes" ( 165 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes 166 | if errorlevel 1 exit /b 1 167 | echo. 168 | echo.The overview file is in %BUILDDIR%/changes. 169 | goto end 170 | ) 171 | 172 | if "%1" == "linkcheck" ( 173 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck 174 | if errorlevel 1 exit /b 1 175 | echo. 176 | echo.Link check complete; look for any errors in the above output ^ 177 | or in %BUILDDIR%/linkcheck/output.txt. 178 | goto end 179 | ) 180 | 181 | if "%1" == "doctest" ( 182 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest 183 | if errorlevel 1 exit /b 1 184 | echo. 185 | echo.Testing of doctests in the sources finished, look at the ^ 186 | results in %BUILDDIR%/doctest/output.txt. 187 | goto end 188 | ) 189 | 190 | :end 191 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # Internal variables. 11 | PAPEROPT_a4 = -D latex_paper_size=a4 12 | PAPEROPT_letter = -D latex_paper_size=letter 13 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 14 | # the i18n builder cannot share the environment and doctrees with the others 15 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 16 | 17 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 18 | 19 | help: 20 | @echo "Please use \`make ' where is one of" 21 | @echo " html to make standalone HTML files" 22 | @echo " dirhtml to make HTML files named index.html in directories" 23 | @echo " singlehtml to make a single large HTML file" 24 | @echo " pickle to make pickle files" 25 | @echo " json to make JSON files" 26 | @echo " htmlhelp to make HTML files and a HTML help project" 27 | @echo " qthelp to make HTML files and a qthelp project" 28 | @echo " devhelp to make HTML files and a Devhelp project" 29 | @echo " epub to make an epub" 30 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 31 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 32 | @echo " text to make text files" 33 | @echo " man to make manual pages" 34 | @echo " texinfo to make Texinfo files" 35 | @echo " info to make Texinfo files and run them through makeinfo" 36 | @echo " gettext to make PO message catalogs" 37 | @echo " changes to make an overview of all changed/added/deprecated items" 38 | @echo " linkcheck to check all external links for integrity" 39 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 40 | 41 | clean: 42 | -rm -rf $(BUILDDIR)/* 43 | 44 | html: 45 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 46 | @echo 47 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 48 | 49 | dirhtml: 50 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 51 | @echo 52 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 53 | 54 | singlehtml: 55 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 56 | @echo 57 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 58 | 59 | pickle: 60 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 61 | @echo 62 | @echo "Build finished; now you can process the pickle files." 63 | 64 | json: 65 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 66 | @echo 67 | @echo "Build finished; now you can process the JSON files." 68 | 69 | htmlhelp: 70 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 71 | @echo 72 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 73 | ".hhp project file in $(BUILDDIR)/htmlhelp." 74 | 75 | qthelp: 76 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 77 | @echo 78 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 79 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 80 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GCCContributorsGuide.qhcp" 81 | @echo "To view the help file:" 82 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GCCContributorsGuide.qhc" 83 | 84 | devhelp: 85 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 86 | @echo 87 | @echo "Build finished." 88 | @echo "To view the help file:" 89 | @echo "# mkdir -p $$HOME/.local/share/devhelp/GCCContributorsGuide" 90 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GCCContributorsGuide" 91 | @echo "# devhelp" 92 | 93 | epub: 94 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 95 | @echo 96 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 97 | 98 | latex: 99 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 100 | @echo 101 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 102 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 103 | "(use \`make latexpdf' here to do that automatically)." 104 | 105 | latexpdf: 106 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 107 | @echo "Running LaTeX files through pdflatex..." 108 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 109 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 110 | 111 | text: 112 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 113 | @echo 114 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 115 | 116 | man: 117 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 118 | @echo 119 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 120 | 121 | texinfo: 122 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 123 | @echo 124 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 125 | @echo "Run \`make' in that directory to run these through makeinfo" \ 126 | "(use \`make info' here to do that automatically)." 127 | 128 | info: 129 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 130 | @echo "Running Texinfo files through makeinfo..." 131 | make -C $(BUILDDIR)/texinfo info 132 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 133 | 134 | gettext: 135 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 136 | @echo 137 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 138 | 139 | changes: 140 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 141 | @echo 142 | @echo "The overview file is in $(BUILDDIR)/changes." 143 | 144 | linkcheck: 145 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 146 | @echo 147 | @echo "Link check complete; look for any errors in the above output " \ 148 | "or in $(BUILDDIR)/linkcheck/output.txt." 149 | 150 | doctest: 151 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 152 | @echo "Testing of doctests in the sources finished, look at the " \ 153 | "results in $(BUILDDIR)/doctest/output.txt." 154 | -------------------------------------------------------------------------------- /getting-started.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2022-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Getting Started 19 | =============== 20 | 21 | "Hello world" from the compiler 22 | ******************************* 23 | 24 | Challenge: 25 | 26 | * add a diagnostic that says "hello world" and emits the function name 27 | for each function that is compiled in the source file. 28 | 29 | * run the compiler under the debugger, and put a breakpoint on the 30 | emission of that diagnostic, and single-step through some of the 31 | compilation 32 | 33 | To do this you'll need to: 34 | 35 | * build GCC from source 36 | 37 | * add a call to:: 38 | 39 | inform (UNKNOWN_LOCATION, "hello world: %qE", cfun->decl); 40 | 41 | somewhere inside the compiler. 42 | 43 | .. note:: 44 | ``cfun`` is a global pointer referencing the **c**\urrent **fun**\ction being compiled. 45 | 46 | 47 | Setting up your build environment 48 | ********************************* 49 | 50 | GCC is a big project, so make sure you have plenty of disk space. 51 | 52 | As of May 2022, on my machine: 53 | 54 | * a ``git`` clone of the source tree occupies 2.5GB of disk space. 55 | 56 | * a "build" tree occupies 6.8GB 57 | 58 | for a total of about 9.5GB. 59 | 60 | It typically takes 1.5 to 2 hours on my machine to do a full build 61 | and test run when testing a patch - but clearly that's going to be 62 | impractical when hacking on a new feature, or fixing a bug: you want 63 | to be able to make a change to a source file and then debug that 64 | change as quickly as possible. 65 | 66 | By default, a build of GCC involves building the source *three times*: 67 | once using the "bootstrapping" compiler, then rebuilding using the GCC 68 | that was just built, then rebuilding a third time, with the second GCC 69 | (built by the first GCC, built by the bootstrapping compiler). This is 70 | a great safety check that we have a working compiler when testing a 71 | patch, but obviously is a major pain when working on the patch itself. 72 | 73 | Hence one important configuration flag is ``--disable-bootstrap``, 74 | which turns off this three-stage bootstrap in favor of simply building 75 | GCC once. 76 | 77 | So the goals of "easy hackability" and "robust testing" are somewhat 78 | in tension. My own way of dealing with this is to spend a lot of 79 | disk space by having multiple working copies, some for working 80 | on patches, and others for *testing* those patches. I typically have 81 | three kinds of working copy: 82 | 83 | (a) a working copy and build directory pair for debugging/development. 84 | I use ``--disable-bootstrap`` when configuring the build, so that 85 | I can quickly rebuild the compiler when making changes. If I 86 | change one source file in the ``SOURCE/gcc`` subdirectory and 87 | invoke ``make -jN`` in the ``BUILDDIR/gcc`` subdirectory it typically 88 | takes about 20 seconds total to rebuild the ``.o`` file, relink the 89 | compiler and run the ``-fself-test`` unit tests (the bulk of 90 | the time is spent in the linker). Without the shortcuts of using 91 | ``--disable-bootstrap`` and restricting the rebuild to the 92 | ``BUILDDIR/gcc`` subdirectory the build would take *much* longer 93 | (measured in minutes or tens of minutes). 94 | 95 | (b) a clean working copy/build directory pair for use as a "control" 96 | when testing patches. We have many thousands of tests in our 97 | test suite, and so, unfortunately, there are usually at least 98 | several of them failing at any given time, so it's helpful when 99 | testing a patch to have something to compare the test results 100 | against. I configure this build with all languages enabled, and 101 | *without* ``--disable-bootstrap``, so it does a full bootstrap. 102 | 103 | (c) a testing source/build directory pair for testing patches, which 104 | is identical to the "control" pair, except for the patches being 105 | tested. 106 | 107 | Separating out the "control" and "testing" directories from the 108 | debugging/development directories helps isolate the testing, and 109 | means that I can work on something else in the 2 hours it takes to 110 | properly test a candidate patch - but means I'm using about 30GB of 111 | disk space, rather than 10GB (and I have to refresh my "control" 112 | builds when I do a rebase of my development trees). 113 | 114 | Whilst you are getting started, I recommend simply creating (a), 115 | using ``--disable-bootstrap`` when configuring the build, and perhaps 116 | only enabling the languages that you care about (to make rebuilds 117 | faster). As you progress to preparing real patches for GCC, you'll 118 | want to add (b) and (c). 119 | 120 | 121 | How I'm doing it on x86_64-pc-linux-gnu 122 | ####################################### 123 | 124 | Following https://gcc.gnu.org/install/, here is how I'd install 125 | a working *development* version to work on the analyzer. 126 | 127 | .. code-block:: bash 128 | 129 | # Install prerequisites - to be done once 130 | sudo apt install perl gawk binutils gcc-multilib \ 131 | python3 python3-pip gzip make tar zstd autoconf automake \ 132 | gettext gperf dejagnu autogen guile-3.0 expect tcl flex texinfo \ 133 | git diffutils patch git-email 134 | 135 | # clone GCC sources 136 | mkdir -p gcc-control 137 | cd gcc-control 138 | git clone git://gcc.gnu.org/git/gcc.git sources 139 | # install the prerequisites using GCC contrib/ script 140 | cd gcc-control 141 | ./sources/contrib/download_prerequisites 142 | mkdir build && cd build 143 | # here you would add --disable-bootstrap for your 'draft' directory 144 | ../sources/configure --prefix "/path/to/gcc-control/install" 145 | # I have 16 cores on my box, so I use -j16 to parallelize as much as possible 146 | # target 'bootstrap' for a bootstrap build. Otherwise omit it. 147 | make -j16 bootstrap 148 | -------------------------------------------------------------------------------- /looking-at-the-generated-asm.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2022-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Looking at the generated assembler 19 | ================================== 20 | 21 | In the previous section, we looked at how the :program:`gcc` driver 22 | program invokes various tools to get its job done. For me, the most 23 | interesting part of that process is the conversion from C source code to 24 | machine code (expressed in the form of assembler) done by the compiler, 25 | :program:`cc1`. 26 | 27 | We can see this part of the process more directly by invoking 28 | :program:`gcc` with the :option:`-S` option (upper-case "S"): 29 | 30 | .. code-block:: sh 31 | 32 | $ gcc -S hello.c 33 | 34 | telling it to merely create an assembler file (with a lower-case 35 | :file:`.s` extension), without doing the later stages we talked about 36 | above:: 37 | 38 | cc1 39 | hello.c -----> hello.s 40 | 41 | 42 | .. code-block:: sh 43 | 44 | gcc -S hello.c 45 | 46 | and in addition to the :file:`hello` executable we built earlier, we now 47 | have a :file:`hello.s` file: 48 | 49 | .. code-block:: sh 50 | 51 | $ ls 52 | hello hello.c hello.s 53 | 54 | Looking in the :file:`hello.s` file we see the generated assembler: 55 | 56 | .. code-block:: asm 57 | 58 | .file "hello.c" 59 | .text 60 | .section .rodata 61 | .LC0: 62 | .string "hello world" 63 | .text 64 | .globl main 65 | .type main, @function 66 | main: 67 | .LFB0: 68 | .cfi_startproc 69 | pushq %rbp 70 | .cfi_def_cfa_offset 16 71 | .cfi_offset 6, -16 72 | movq %rsp, %rbp 73 | .cfi_def_cfa_register 6 74 | movl $.LC0, %edi 75 | call puts 76 | movl $0, %eax 77 | popq %rbp 78 | .cfi_def_cfa 7, 8 79 | ret 80 | .cfi_endproc 81 | .LFE0: 82 | .size main, .-main 83 | .ident "GCC: (GNU) 10.3.1 20210422 (Red Hat 10.3.1-1)" 84 | .section .note.GNU-stack,"",@progbits 85 | 86 | It's not important yet to be able to fully understand the assembler, 87 | but for now just know that we have some metadata at the top, followed 88 | by the user's :c:func:`main` function, and then some trailing 89 | metadata. 90 | 91 | You can even see how the assembler relates to the C code by passing 92 | :option:`-fverbose-asm` to :program:`gcc`: 93 | 94 | .. code-block:: sh 95 | 96 | $ gcc -S hello.c -fverbose-asm 97 | 98 | which leads to this in the output :file:`hello.s` file: 99 | 100 | .. code-block:: asm 101 | 102 | .file "hello.c" 103 | # GNU C17 (GCC) version 10.3.1 20210422 (Red Hat 10.3.1-1) (x86_64-redhat-linux) 104 | # compiled by GNU C version 10.3.1 20210422 (Red Hat 10.3.1-1), GMP version 6.2.0, MPFR version 4.1.0-p9, MPC version 1.1.0, isl version none 105 | # GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 106 | # options passed: hello.c -mtune=generic -march=x86-64 -fverbose-asm 107 | # options enabled: -faggressive-loop-optimizations -fallocation-dce 108 | # -fasynchronous-unwind-tables -fauto-inc-dec -fdelete-null-pointer-checks 109 | # -fdwarf2-cfi-asm -fearly-inlining -feliminate-unused-debug-symbols 110 | # -feliminate-unused-debug-types -ffp-int-builtin-inexact -ffunction-cse 111 | # -fgcse-lm -fgnu-unique -fident -finline-atomics -fipa-stack-alignment 112 | # -fira-hoist-pressure -fira-share-save-slots -fira-share-spill-slots 113 | # -fivopts -fkeep-static-consts -fleading-underscore -flifetime-dse 114 | # -fmath-errno -fmerge-debug-strings -fpeephole -fplt 115 | # -fprefetch-loop-arrays -freg-struct-return 116 | # -fsched-critical-path-heuristic -fsched-dep-count-heuristic 117 | # -fsched-group-heuristic -fsched-interblock -fsched-last-insn-heuristic 118 | # -fsched-rank-heuristic -fsched-spec -fsched-spec-insn-heuristic 119 | # -fsched-stalled-insns-dep -fschedule-fusion -fsemantic-interposition 120 | # -fshow-column -fshrink-wrap-separate -fsigned-zeros 121 | # -fsplit-ivs-in-unroller -fssa-backprop -fstdarg-opt 122 | # -fstrict-volatile-bitfields -fsync-libcalls -ftrapping-math -ftree-cselim 123 | # -ftree-forwprop -ftree-loop-if-convert -ftree-loop-im -ftree-loop-ivcanon 124 | # -ftree-loop-optimize -ftree-parallelize-loops= -ftree-phiprop 125 | # -ftree-reassoc -ftree-scev-cprop -funit-at-a-time -funwind-tables 126 | # -fverbose-asm -fzero-initialized-in-bss -m128bit-long-double -m64 -m80387 127 | # -malign-stringops -mavx256-split-unaligned-load 128 | # -mavx256-split-unaligned-store -mfancy-math-387 -mfp-ret-in-387 -mfxsr 129 | # -mglibc -mieee-fp -mlong-double-80 -mmmx -mno-sse4 -mpush-args -mred-zone 130 | # -msse -msse2 -mstv -mtls-direct-seg-refs -mvzeroupper 131 | 132 | .text 133 | .section .rodata 134 | .LC0: 135 | .string "hello world" 136 | .text 137 | .globl main 138 | .type main, @function 139 | main: 140 | .LFB0: 141 | .cfi_startproc 142 | pushq %rbp # 143 | .cfi_def_cfa_offset 16 144 | .cfi_offset 6, -16 145 | movq %rsp, %rbp #, 146 | .cfi_def_cfa_register 6 147 | # hello.c:4: printf ("hello world\n"); 148 | movl $.LC0, %edi #, 149 | call puts # 150 | # hello.c:5: return 0; 151 | movl $0, %eax #, _3 152 | # hello.c:6: } 153 | popq %rbp # 154 | .cfi_def_cfa 7, 8 155 | ret 156 | .cfi_endproc 157 | .LFE0: 158 | .size main, .-main 159 | .ident "GCC: (GNU) 10.3.1 20210422 (Red Hat 10.3.1-1)" 160 | .section .note.GNU-stack,"",@progbits 161 | 162 | In particular, looking at the heart of the :c:func:`main` function we 163 | now have comments showing us how the some of the assembler relates to 164 | specific lines in the C source file: 165 | 166 | .. code-block:: asm 167 | 168 | # hello.c:4: printf ("hello world\n"); 169 | movl $.LC0, %edi #, 170 | call puts # 171 | # hello.c:5: return 0; 172 | movl $0, %eax #, _3 173 | # hello.c:6: } 174 | popq %rbp # 175 | .cfi_def_cfa 7, 8 176 | ret 177 | 178 | We'll look at how :program:`cc1` actually turns the C into assembler in 179 | the next section. 180 | -------------------------------------------------------------------------------- /gotchas-and-faq.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | "Gotchas" and FAQs 19 | ------------------ 20 | 21 | What language is GCC implemented in? 22 | ************************************ 23 | 24 | The short answer: a conservative subset of C++11. 25 | 26 | Longer answer: 27 | 28 | GCC is an old project, originally implemented in C (in the late 1980s). 29 | 30 | In GCC 4.8 (released in 2013) we migrated our implementation language to 31 | C++. 32 | 33 | We stuck to C++98 from 2013 through 2021, and as of GCC 11 in 2021 started 34 | allowing some C++11 features (such as ``auto``, range-based ``for`` loops, 35 | and ``std::unique_ptr``). 36 | 37 | Although we implement the most recent updates to the C++ language, 38 | for our own implementation we restrict ourselves to a fairly conservative 39 | subset of C++. This is because GCC is so often used for bootstrapping new 40 | OS and CPU configurations, so we want to make it easy to build GCC itself 41 | using older compilers that might themselves be buggy. 42 | 43 | Addititionally, we have some tools which scan the source tree during the 44 | build process, so we must use the subset of C++ that those tools can 45 | handle, in particular, ``gengtype`` (see 46 | :ref:`GCC's garbage collector `) - or extend those tools. 47 | 48 | The official notes on how we use C++ as an implementation language are 49 | at https://gcc.gnu.org/codingconventions.html#Cxx_Conventions 50 | 51 | 52 | I tried grepping for `struct foo` but can't find it! 53 | **************************************************** 54 | 55 | It's often difficult to grep for the declaration of, say, ``struct foo`` 56 | in the GCC sources due to the presence of "GTY" markers. For example, 57 | in the C++ frontend, token are handled using ``struct cp_token``, which 58 | is defined as: 59 | 60 | .. code-block:: c++ 61 | 62 | /* A C++ token. */ 63 | 64 | struct GTY (()) cp_token { 65 | /* ...fields go here... */ 66 | }; 67 | 68 | These "GTY" markers are annotations to the types, and are used by GCC's 69 | garbage-collector. They're stripped away by the preprocessor when building 70 | GCC itself, but get used by a tool during the build called ``gengtype``. 71 | 72 | TODO: how to search for them? 73 | 74 | 75 | How do I debug GCC? 76 | ******************* 77 | 78 | The ``gcc`` binary is actually a relatively small "driver" program, which 79 | parses some command-line options, and then invokes one or more other 80 | programs to do the real work. See the notes in :ref:`debugging` for 81 | an explanation of how to debug. 82 | 83 | 84 | What does "PR" mean, e.g. "PR c/71610"? 85 | *************************************** 86 | 87 | We use an instance of Bugzilla as our bug tracker. We refer to bugs 88 | as "Problem Reports", or "PR" for short. For example, the bug with 89 | ID 71610 affects the "c" component, and might be referred to as 90 | "PR c/71610" in discussions on our mailing lists, and in ChangeLog 91 | entries. 92 | 93 | To see the bug report in Bugzilla, go to 94 | https://gcc.gnu.org/PRnnnnn 95 | 96 | For example, for PR c/71610, see 97 | https://gcc.gnu.org/PR71610 98 | 99 | For more information on the bug tracker and filing bugs, see 100 | https://gcc.gnu.org/bugs/ 101 | 102 | I want to try my hands on a bug, but cannot assign it to myself, why? 103 | ********************************************************************* 104 | 105 | The best way to get familiar with GCC is to find yourself an easy bug 106 | on our Bugzilla you believe you can fix. It will get you more familiar 107 | with the code, debugging GCC, running the testsuite and the whole "patching" 108 | process - while already contributing to GCC. Really all pros no cons ;-). 109 | 110 | So here you are, you have found your bug either by requesting one on the 111 | mail list gcc@gcc.gnu.org, on the IRC channel irc://irc.oftc.net/#gcc, or 112 | by skimming through the `Bugzilla`_. Thus you want to assign it to yourself. 113 | However, the *Assignee* field is uneditable, **even though you are connected**. 114 | 115 | The reason is simple: by default, accounts created on our Bugzilla 116 | only have limited access. To get write access to fields such as *Assignee*, 117 | you will need to log in using a sourceware.org / gcc.gnu.org email 118 | address that you can get by following the steps described here 119 | ``_. 120 | 121 | .. list-table:: 122 | :header-rows: 1 123 | 124 | * - With regular account 125 | - With 'gcc.gnu.org' account 126 | * - .. image:: images/grayed-out-assignee.bugzilla.png 127 | - .. image:: images/sourceware-login-assignee.bugzilla.png 128 | 129 | Is "ggc" a typo? 130 | **************** 131 | 132 | "ggc" (as opposed to "gcc") refers to :ref:`GCC's garbage collector `. 133 | 134 | 135 | Compiler basics 136 | *************** 137 | 138 | If you're interested in GCC's internals, it's probably worth at least 139 | skimming an introductory course on compilers in general. Some helpful 140 | terms follow: 141 | 142 | "build" vs "host" vs "target" 143 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 144 | 145 | For a compiler, we can talk about: 146 | 147 | * the "build" system: the system the compiler is built on 148 | 149 | * the "host" system: the system the compiler runs on 150 | 151 | * the "target" system: the system that the compiler is generating code 152 | for 153 | 154 | By way of example, many years ago in a previous job, I wrote videogames, 155 | using an older version of gcc. If I'm remembering things correctly, 156 | this gcc had been built on a Linux box by another company, ran on my 157 | Windows 95 desktop machine, and generated code for a particular games 158 | console that was popular at the time. In this example: 159 | 160 | * the "build" system was whatever Linux system the toolchain provider 161 | used when building the gcc that got shipped with the console 162 | development kit 163 | 164 | * the "host" system was my desktop PC, a 32-bit i386 system running 165 | Windows 95 166 | 167 | * the "target" system was a games console with a MIPS R3000 CPU (a kind 168 | of RISC chip), with no real operating system to speak of 169 | 170 | Often all three will be the same: when I'm developing GCC I typically 171 | build and run gcc on my x86_64 Fedora box, and it builds binaries for 172 | the same. We speak of "cross compilation" when the host and target are 173 | different systems. 174 | 175 | .. _Bugzilla: https://gcc.gnu.org/bugzilla 176 | -------------------------------------------------------------------------------- /working-with-the-testsuite.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2017-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Working with the testsuite 19 | ========================== 20 | 21 | Running just one test (or just a few) 22 | ************************************* 23 | 24 | 1) Find the pertinent Tcl script that runs the test: a .exp script in 25 | the same directory, or one of the ancestors' directories. The significant 26 | part is the filename. 27 | 28 | For example, for test case 29 | ``gcc/testsuite/gcc.dg/pragma-diag-1.c``, it's 30 | ``gcc/testsuite/gcc.dg/dg.exp``, where the filename is ``dg.exp``. 31 | 32 | 2) Figure out the appropriate "make" target, normally based on the 33 | source language for the test. For the above example, it's ``check-gcc``. 34 | 35 | Other targets are e.g.: ``check-c++``, ``check-fortran``, ``check-ada`` 36 | or ``check-go``. For a full list see ``Makefile.def`` in the repository 37 | root directory and grep for ``check-c++``. 38 | 39 | Those language targets also run tests for compiler support libraries for 40 | the given language. For example ``check-ada`` adds and runs tests for 41 | ``libada``, use ``check-gcc-ada`` to run only the compiler tests but 42 | no library tests. 43 | 44 | 3) Run make in your ``BUILDDIR/gcc`` (not in ``BUILDDIR`` or you will also 45 | check the libraries), passing in a suitable value for ``RUNTESTFLAGS`` based 46 | on the filename found in step 1 above. 47 | 48 | For this case, giving it a couple of ``-v`` flags for verbosity (so that 49 | we can see the command-line of the compiler invocation) it would be:: 50 | 51 | $ make -jN && make check-gcc RUNTESTFLAGS="-v -v dg.exp=pragma-diag-1.c" 52 | 53 | for some N; I like the ``make && make check-FOO`` construction to ensure 54 | that the compiler is rebuilt before running the tests. 55 | 56 | You can also use wildcards e.g.:: 57 | 58 | make -j64 && make check-gcc RUNTESTFLAGS="-v -v dg.exp=pragma-diag-*.c" 59 | 60 | (and can use ``-jN`` for some N on the ``make check-FOO`` invocation if 61 | there are a lot of tests; I tend not to use it for a small number of tests, 62 | to avoid interleaving of output in the logs). 63 | 64 | Testcases that apply to both C and C++ should live in ``c-c++-common``. 65 | You can run them by making both the ``check-gcc`` and ``check-g++`` 66 | Makefile targets. Adapting the idea from above, here's an invocation I 67 | used whilst working on a patch:: 68 | 69 | make -k -j64 \ 70 | && make check-gcc check-g++ \ 71 | RUNTESTFLAGS="-v -v dg.exp=Wformat-pr88257.c" 72 | 73 | Here's a yet more complicated example, which runs various tests from both 74 | ``dg.exp`` and ``tree-ssa.exp`` (with multiple wildcards), and runs them 75 | for both 32-bit and 64-bit ABIs:: 76 | 77 | make check-gcc \ 78 | RUNTESTFLAGS="--target_board=unix\{-m32,-m64\} dg.exp='pr10474.c pr15698*.c' tree-ssa.exp=20030530-2.c" 79 | 80 | 81 | What tests did I just run? 82 | ************************** 83 | 84 | By default DejaGnu merely emits the names of unexpected results: typically 85 | FAILs results for test failures (and XPASS for unexpected successes), along 86 | with a summary at the end. 87 | 88 | If you want to see all of the results, look for the ``.sum`` file (e.g. 89 | in ``testsuite/gcc/gcc.sum``. 90 | 91 | For example, whilst working on a bug fix, I invoked the tests via:: 92 | 93 | make check-gcc RUNTESTFLAGS="-v -v --target_board=unix\{-m32,-m64\} dg.exp=*sarif*.c" 94 | 95 | and got a ``testsuite/gcc/gcc.sum`` containing:: 96 | 97 | Test run by david on Fri Mar 24 10:10:20 2023 98 | Native configuration is x86_64-pc-linux-gnu 99 | 100 | === gcc tests === 101 | 102 | Schedule of variations: 103 | unix/-m32 104 | unix/-m64 105 | 106 | Running target unix/-m32 107 | Running /home/david/coding/gcc-sarif-support/src/gcc/testsuite/gcc.dg/dg.exp ... 108 | FAIL: gcc.dg/diagnostic-input-charset-sarif-1.c (test for excess errors) 109 | PASS: c-c++-common/diagnostic-format-sarif-file-1.c -Wc++-compat (test for excess errors) 110 | PASS: c-c++-common/diagnostic-format-sarif-file-1.c -Wc++-compat scan-sarif-file "version": "2.1.0" 111 | [...snip...] 112 | PASS: c-c++-common/diagnostic-format-sarif-file-FIXME.c -Wc++-compat scan-sarif-file "text": "invalid UTF-8 character <80>" 113 | PASS: c-c++-common/diagnostic-format-sarif-file-FIXME.c -Wc++-compat scan-sarif-file "text": "invalid UTF-8 character <99>" 114 | PASS: c-c++-common/diagnostic-format-sarif-file-Winvalid-utf8.c -Wc++-compat (test for excess errors) 115 | XFAIL: c-c++-common/diagnostic-format-sarif-file-bad-encoding.c -Wc++-compat (test for excess errors) 116 | XFAIL: c-c++-common/diagnostic-format-sarif-file-malformed-utf8.c -Wc++-compat (test for excess errors) 117 | 118 | === gcc Summary for unix/-m32 === 119 | 120 | # of expected passes 71 121 | # of unexpected failures 1 122 | # of expected failures 4 123 | Running target unix/-m64 124 | Running /home/david/coding/gcc-sarif-support/src/gcc/testsuite/gcc.dg/dg.exp ... 125 | FAIL: gcc.dg/diagnostic-input-charset-sarif-1.c (test for excess errors) 126 | PASS: c-c++-common/diagnostic-format-sarif-file-1.c -Wc++-compat (test for excess errors) 127 | PASS: c-c++-common/diagnostic-format-sarif-file-1.c -Wc++-compat scan-sarif-file "version": "2.1.0" 128 | [...snip...] 129 | PASS: c-c++-common/diagnostic-format-sarif-file-FIXME.c -Wc++-compat scan-sarif-file "text": "invalid UTF-8 character <99>" 130 | PASS: c-c++-common/diagnostic-format-sarif-file-Winvalid-utf8.c -Wc++-compat (test for excess errors) 131 | XFAIL: c-c++-common/diagnostic-format-sarif-file-bad-encoding.c -Wc++-compat (test for excess errors) 132 | XFAIL: c-c++-common/diagnostic-format-sarif-file-malformed-utf8.c -Wc++-compat (test for excess errors) 133 | 134 | === gcc Summary for unix/-m64 === 135 | 136 | # of expected passes 71 137 | # of unexpected failures 1 138 | # of expected failures 4 139 | 140 | === gcc Summary === 141 | 142 | # of expected passes 142 143 | # of unexpected failures 2 144 | # of expected failures 8 145 | /home/david/coding/gcc-sarif-support/build/gcc/xgcc version 13.0.1 20230321 (experimental) (GCC) 146 | 147 | I never get the wildcard invocation correct on the first time, so this is 148 | useful for double-checking that the tests I hoped to run are actually 149 | running and passing. 150 | 151 | If you want even more detail, see the ``.log`` file (such as 152 | ``testsuite/gcc/gcc.log``). You can use this to find the command lines 153 | used to invoke gcc, which may be helpful when debugging why a test case 154 | is failing. 155 | 156 | 157 | "test for excess errors" 158 | ************************ 159 | 160 | If a DejaGnu test is failing with "test for excess errors" 161 | you can go into gcc/testsuite/lib/prune.exp and uncomment this line 162 | within ``proc prune_gcc_output``: 163 | 164 | .. code-block:: tcl 165 | 166 | #send_user "After:$text\n" 167 | 168 | to: 169 | 170 | .. code-block:: tcl 171 | 172 | send_user "After:$text\n" 173 | 174 | This will print any messages that weren't pruned by ``dg-`` directives. 175 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # GCC Contributors Guide documentation build configuration file, created by 4 | # sphinx-quickstart on Thu Jul 21 17:39:25 2016. 5 | # 6 | # This file is execfile()d with the current directory set to its containing dir. 7 | # 8 | # Note that not all possible configuration values are present in this 9 | # autogenerated file. 10 | # 11 | # All configuration values have a default; values that are commented out 12 | # serve to show the default. 13 | 14 | import sys, os 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | #sys.path.insert(0, os.path.abspath('.')) 20 | 21 | # -- General configuration ----------------------------------------------------- 22 | 23 | # If your documentation needs a minimal Sphinx version, state it here. 24 | #needs_sphinx = '1.0' 25 | 26 | # Add any Sphinx extension module names here, as strings. They can be extensions 27 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 28 | extensions = [] 29 | 30 | # Add any paths that contain templates here, relative to this directory. 31 | templates_path = ['_templates'] 32 | 33 | # The suffix of source filenames. 34 | source_suffix = '.rst' 35 | 36 | # The encoding of source files. 37 | #source_encoding = 'utf-8-sig' 38 | 39 | # The master toctree document. 40 | master_doc = 'index' 41 | 42 | # General information about the project. 43 | project = u'GCC Contributors Guide' 44 | copyright = u'2016-2022, David Malcolm' 45 | 46 | # The version info for the project you're documenting, acts as replacement for 47 | # |version| and |release|, also used in various other places throughout the 48 | # built documents. 49 | # 50 | # The short X.Y version. 51 | version = '0.1' 52 | # The full version, including alpha/beta/rc tags. 53 | release = '0.1' 54 | 55 | # The language for content autogenerated by Sphinx. Refer to documentation 56 | # for a list of supported languages. 57 | #language = None 58 | 59 | # There are two options for replacing |today|: either, you set today to some 60 | # non-false value, then it is used: 61 | #today = '' 62 | # Else, today_fmt is used as the format for a strftime call. 63 | #today_fmt = '%B %d, %Y' 64 | 65 | # List of patterns, relative to source directory, that match files and 66 | # directories to ignore when looking for source files. 67 | exclude_patterns = ['_build'] 68 | 69 | # The reST default role (used for this markup: `text`) to use for all documents. 70 | #default_role = None 71 | 72 | # If true, '()' will be appended to :func: etc. cross-reference text. 73 | #add_function_parentheses = True 74 | 75 | # If true, the current module name will be prepended to all description 76 | # unit titles (such as .. function::). 77 | #add_module_names = True 78 | 79 | # If true, sectionauthor and moduleauthor directives will be shown in the 80 | # output. They are ignored by default. 81 | #show_authors = False 82 | 83 | # The name of the Pygments (syntax highlighting) style to use. 84 | pygments_style = 'sphinx' 85 | 86 | # A list of ignored prefixes for module index sorting. 87 | #modindex_common_prefix = [] 88 | 89 | 90 | # -- Options for HTML output --------------------------------------------------- 91 | 92 | # The theme to use for HTML and HTML Help pages. See the documentation for 93 | # a list of builtin themes. 94 | html_theme = 'sphinxdoc' 95 | 96 | # Theme options are theme-specific and customize the look and feel of a theme 97 | # further. For a list of options available for each theme, see the 98 | # documentation. 99 | #html_theme_options = {} 100 | 101 | # Add any paths that contain custom themes here, relative to this directory. 102 | #html_theme_path = [] 103 | 104 | # The name for this set of Sphinx documents. If None, it defaults to 105 | # " v documentation". 106 | #html_title = None 107 | 108 | # A shorter title for the navigation bar. Default is the same as html_title. 109 | #html_short_title = None 110 | 111 | # The name of an image file (relative to this directory) to place at the top 112 | # of the sidebar. 113 | #html_logo = None 114 | 115 | # The name of an image file (within the static path) to use as favicon of the 116 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 117 | # pixels large. 118 | #html_favicon = None 119 | 120 | # Add any paths that contain custom static files (such as style sheets) here, 121 | # relative to this directory. They are copied after the builtin static files, 122 | # so a file named "default.css" will overwrite the builtin "default.css". 123 | html_static_path = ['_static'] 124 | 125 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 126 | # using the given strftime format. 127 | #html_last_updated_fmt = '%b %d, %Y' 128 | 129 | # If true, SmartyPants will be used to convert quotes and dashes to 130 | # typographically correct entities. 131 | #html_use_smartypants = True 132 | 133 | # Custom sidebar templates, maps document names to template names. 134 | #html_sidebars = {} 135 | 136 | # Additional templates that should be rendered to pages, maps page names to 137 | # template names. 138 | #html_additional_pages = {} 139 | 140 | # If false, no module index is generated. 141 | #html_domain_indices = True 142 | 143 | # If false, no index is generated. 144 | #html_use_index = True 145 | 146 | # If true, the index is split into individual pages for each letter. 147 | #html_split_index = False 148 | 149 | # If true, links to the reST sources are added to the pages. 150 | #html_show_sourcelink = True 151 | 152 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 153 | #html_show_sphinx = True 154 | 155 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 156 | #html_show_copyright = True 157 | 158 | # If true, an OpenSearch description file will be output, and all pages will 159 | # contain a tag referring to it. The value of this option must be the 160 | # base URL from which the finished HTML is served. 161 | #html_use_opensearch = '' 162 | 163 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 164 | #html_file_suffix = None 165 | 166 | # Output file base name for HTML help builder. 167 | htmlhelp_basename = 'GCCContributorsGuidedoc' 168 | 169 | 170 | # -- Options for LaTeX output -------------------------------------------------- 171 | 172 | latex_elements = { 173 | # The paper size ('letterpaper' or 'a4paper'). 174 | #'papersize': 'letterpaper', 175 | 176 | # The font size ('10pt', '11pt' or '12pt'). 177 | #'pointsize': '10pt', 178 | 179 | # Additional stuff for the LaTeX preamble. 180 | #'preamble': '', 181 | } 182 | 183 | # Grouping the document tree into LaTeX files. List of tuples 184 | # (source start file, target name, title, author, documentclass [howto/manual]). 185 | latex_documents = [ 186 | ('index', 'GCCContributorsGuide.tex', u'GCC Contributors Guide Documentation', 187 | u'David Malcolm', 'manual'), 188 | ] 189 | 190 | # The name of an image file (relative to this directory) to place at the top of 191 | # the title page. 192 | #latex_logo = None 193 | 194 | # For "manual" documents, if this is true, then toplevel headings are parts, 195 | # not chapters. 196 | #latex_use_parts = False 197 | 198 | # If true, show page references after internal links. 199 | #latex_show_pagerefs = False 200 | 201 | # If true, show URL addresses after external links. 202 | #latex_show_urls = False 203 | 204 | # Documents to append as an appendix to all manuals. 205 | #latex_appendices = [] 206 | 207 | # If false, no module index is generated. 208 | #latex_domain_indices = True 209 | 210 | 211 | # -- Options for manual page output -------------------------------------------- 212 | 213 | # One entry per manual page. List of tuples 214 | # (source start file, name, description, authors, manual section). 215 | man_pages = [ 216 | ('index', 'gcccontributorsguide', u'GCC Contributors Guide Documentation', 217 | [u'David Malcolm'], 1) 218 | ] 219 | 220 | # If true, show URL addresses after external links. 221 | #man_show_urls = False 222 | 223 | 224 | # -- Options for Texinfo output ------------------------------------------------ 225 | 226 | # Grouping the document tree into Texinfo files. List of tuples 227 | # (source start file, target name, title, author, 228 | # dir menu entry, description, category) 229 | texinfo_documents = [ 230 | ('index', 'GCCContributorsGuide', u'GCC Contributors Guide Documentation', 231 | u'David Malcolm', 'GCCContributorsGuide', 'One line description of project.', 232 | 'Miscellaneous'), 233 | ] 234 | 235 | # Documents to append as an appendix to all manuals. 236 | #texinfo_appendices = [] 237 | 238 | # If false, no module index is generated. 239 | #texinfo_domain_indices = True 240 | 241 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 242 | #texinfo_show_urls = 'footnote' 243 | -------------------------------------------------------------------------------- /how-to-improve-the-location-of-a-diagnostic.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | How to improve the location of a gcc diagnostic 19 | =============================================== 20 | 21 | A user filed a bug about a bad location in a warning. It was marked as 22 | an "easyhack" in bugzilla, and I had a go at fixing it. 23 | 24 | I thought it may be useful for new GCC developers if I document what I 25 | did to fix it. 26 | 27 | FWIW, the bug was PR c/71610 28 | i.e. https://gcc.gnu.org/bugzilla/show_bug.cgi?id=71610) 29 | ("Improve location for "warning: ISO C restricts enumerator values to 30 | range of 'int' [-Wpedantic]"?"). 31 | 32 | 33 | Step 1: create a minimal reproducer for the diagnostic 34 | ------------------------------------------------------ 35 | 36 | This was easy for this bug: I copied it from the bug report. Try to 37 | avoid ``#include`` if possible; start with the simplest possible reproducer 38 | (to minimize effort in the debugger), and work from there. 39 | 40 | If you're working on a bug in our bugzilla it's good to click on the 41 | "take" button next to "Assignee" to mark yourself as assignee, and to 42 | set the status to ASSIGNED, so that we don't duplicate effort. 43 | 44 | 45 | Step 2: create a file under the relevant subdirectory of gcc/testsuite 46 | ---------------------------------------------------------------------- 47 | 48 | This will be under one of ``gcc.dg``, ``g++.dg`` or ``c-c++-common``. 49 | If possible, create it under ``c-c++-common`` so that we can test both the 50 | C and C++ frontends. 51 | 52 | I created a file called ``pr71610.c`` under ``c-c++-common``. (If this was 53 | for a specific warning, the name of the warning may have been better, 54 | but my case was part of ``-Wpedantic``, which is too broad for a testcase 55 | title). 56 | 57 | 58 | Step 3: run the reproducer under DejaGnu 59 | ---------------------------------------- 60 | 61 | With a freshly built gcc, I ran the following from the "gcc" build 62 | directory: 63 | 64 | .. code-block:: console 65 | 66 | make -jN -k && make check-gcc RUNTESTFLAGS="-v -v dg.exp=pr71610*" 67 | 68 | changing the "N" in ``-jN`` to reflect the number of cores on my box. 69 | 70 | This ensures that the compiler is rebuilt (useful when making changes), 71 | and then runs the C compiler testsuite, filtering to just the new tests 72 | that I'd added. 73 | 74 | Given that the test case is for ``c-c++-common``, it's also worth running 75 | ``make check-g++`` to run the C++ compiler on the same tests. 76 | 77 | I added DejaGnu directives to the test file to ensure that the test was 78 | run with appropriate command-line flags to trigger the behavior in 79 | question. In this case, -Wpedantic is needed, and we want to ensure 80 | that the correct source ranges are printed so ``-fdiagnostics-show-caret`` 81 | is also needed (otherwise the testsuite defaults to 82 | ``-fno-diagnostics-show-caret``). 83 | 84 | Hence I added: 85 | 86 | .. code-block:: c 87 | 88 | /* { dg-options "-pedantic -fdiagnostics-show-caret" } */ 89 | 90 | to the test case. 91 | 92 | Given that I wanted to test ranges, I renamed some of the identifiers 93 | in the test case to avoid using 1-character names. That way it's easy 94 | to verify that all of the identifier is properly underlined (since 95 | finish != the start for a multi-character identifier). 96 | 97 | At this point you should have a reproducer that runs within our DejaGnu 98 | -based test suite, and demonstrates the problem. 99 | 100 | Adding ``-v -v`` to ``RUNTESTFLAGS`` gives us the command-line invocations 101 | of the test cases. Copy and paste this and verify that the reproducer can 102 | be run directly from the command-line. This brings us to... 103 | 104 | 105 | Step 4: run the reproducer under gdb 106 | ------------------------------------ 107 | 108 | Having created a reproducer and identified a command-line invocation 109 | for running it under the testsuite, add the following to the end of the 110 | command-line: 111 | 112 | .. code-block:: console 113 | 114 | -wrapper gdb,--args 115 | 116 | This will make the gcc driver run "cc1" under gdb. 117 | 118 | A good breakpoint location is diagnostic_show_locus. This is run 119 | whenever a diagnostic is actually emitted (as opposed to, say, warning 120 | and warning_at, which are called many times as the compiler runs, with 121 | most of the calls doing nothing): 122 | 123 | .. code-block:: console 124 | 125 | (gdb) break diagnostic_show_locus 126 | (gdb) run 127 | 128 | Hopefully the debugger now hits the breakpoint. At this point, go up 129 | the stack until you reach the frontend call that emits the diagnostic 130 | (in my case, this was a call to pedwarn). It's usually helpful to now 131 | put a breakpoint on the actual emission point (to save a step when 132 | re-running). 133 | 134 | 135 | Step 5: figure out where the location is coming from, and improve it 136 | -------------------------------------------------------------------- 137 | 138 | In the debugger you can investigate which location is being used for 139 | the diagnostic, and use a better one. 140 | 141 | Many older calls to the diagnostic subsystem implicitly use the 142 | ``input_location`` global, which is typically the location (and range) of 143 | the token currently being parsed. (We're aiming to eventually eliminate 144 | implicit uses of ``input_location``). 145 | 146 | In my case, the code was using: 147 | 148 | .. code-block:: c++ 149 | 150 | value_loc = c_parser_peek_token (parser)->location; 151 | 152 | which gets the location (and range) of the first token within an 153 | expression. 154 | 155 | Usually it's better to display the range of an entire expression rather 156 | than just a token. 157 | 158 | Some expression tree nodes have locations, others do not. I hope to 159 | fix this for gcc 7. In the meantime, the C frontend has a 160 | ``struct c_expr`` which captures the range of an expression during 161 | parsing (even for those that don't have location information), and the 162 | C++ frontend has a ``class cp_expr`` which works similarly, capturing the 163 | location and range (again, only during parsing). Or you can use: 164 | 165 | .. code-block:: c++ 166 | 167 | EXPR_LOC_OR_LOC (expr, fallback_location) 168 | 169 | If you want to emit multiple locations from a test, or emit fix-it 170 | hints, try using the rich_location class (see libcpp/include/line 171 | map.h). 172 | 173 | 174 | Step 6: add more test cases 175 | --------------------------- 176 | 177 | Assuming you've made a change to update the location that's used for a 178 | diagnostic, think about what could break, and try to extend the test 179 | case beyond the minimal reproducer to cover other cases. It's good to 180 | think from two perspectives: developer ("make it work") and QA ("try to 181 | break it"). 182 | 183 | If you're using ``-fdiagnostics-show-caret`` to capture the range 184 | information, you can use dg-{begin|end}-multiline-output to express 185 | testing for this output. For example: 186 | 187 | .. code-block:: c 188 | 189 | /* { dg-options "-fdiagnostics-show-caret" } */ 190 | void test (void) 191 | { 192 | enum { c1 = "not int", /* { dg-error "14: enumerator value for .c1. is not an integer constant" } */ 193 | /* { dg-begin-multiline-output "" } 194 | enum { c1 = "not int", 195 | ^~~~~~~~~ 196 | { dg-end-multiline-output "" } */ 197 | 198 | c_end }; 199 | } 200 | 201 | It's preferable to consolidate multiple related tests into one source 202 | file, where practical, to minimize the per-source-file overhead when 203 | running the test suite. 204 | 205 | 206 | Step 7: bootstrap & regression test 207 | ----------------------------------- 208 | 209 | Assuming you have a patch that works, follow the usual GCC testing 210 | steps: https://gcc.gnu.org/contribute.html to ensure it doesn't break anything. 211 | 212 | FWIW I have a script for building both unpatched ("control") and 213 | patched ("experiment") versions of gcc, bootstrapping and running the 214 | regression-test suite, and comparing the results: https://github.com/davidmalcolm/gcc-build 215 | 216 | Write a ChangeLog. I do this whilst it's bootstrapping, using a script 217 | here: https://github.com/davidmalcolm/gcc-refactoring-scripts/blob/master/generate-changelog.py 218 | which makes it easier to generate a ChangeLog (by parsing the output of "git show"). 219 | 220 | 221 | Step 8: post to gcc-patches 222 | --------------------------- 223 | 224 | FWIW, my patch for the issue described above is here: 225 | https://gcc.gnu.org/ml/gcc-patches/2016-06/msg01658.html 226 | 227 | 228 | Step 9: respond to patch review 229 | ------------------------------- 230 | 231 | 232 | Step 10: push to git 233 | -------------------- 234 | 235 | Once the patch is approved, push it to master. 236 | 237 | -------------------------------------------------------------------------------- /debugging.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | .. _debugging: 19 | 20 | Debugging GCC 21 | ============= 22 | 23 | The ``gcc`` binary is actually a relatively small "driver" program, which 24 | parses some command-line options, and then invokes one or more other 25 | programs to do the real work. 26 | 27 | Consider compiling a simple hello world C program: 28 | 29 | .. literalinclude:: hello.c 30 | :language: c 31 | 32 | to generate an ``a.out`` binary: 33 | 34 | .. code-block:: console 35 | 36 | $ gcc hello.c 37 | $ ./a.out 38 | Hello world 39 | 40 | Internally, the driver will invoke ``cc1`` (the C compiler), which 41 | converts the .c code to a .s assembler file. Assuming this succeeds the 42 | driver will typically then invoke ``as`` (the assembler), then the linker. 43 | 44 | Given that, how do we debug the C compiler? The easier way is to add 45 | ``-wrapper gdb,--args`` to the `gcc` command-line: 46 | 47 | .. code-block:: console 48 | 49 | # Invoke "cc1" (and "as", etc) under gdb: 50 | $ gcc hello.c -wrapper gdb,--args 51 | 52 | The ``gcc`` driver will then invoke ``cc1`` under ``gdb``, and you can 53 | set breakpoints, and step through the code. 54 | 55 | .. note:: 56 | 57 | If you ever need to debug the driver itself, you can simply run it under 58 | gdb in the normal way: 59 | 60 | .. code-block:: console 61 | 62 | # Invoke the "gcc" driver under gdb: 63 | $ gdb --args gcc hello.c 64 | 65 | I find myself doing this much less frequently than the 66 | ``-wrapper gdb,--args`` invocation for debugging ``cc1`` though. 67 | 68 | .. _valgrind: 69 | 70 | You can invoke other debugging programs this way, for example, valgrind: 71 | 72 | .. code-block:: console 73 | 74 | # Invoke "cc1" (and "as", etc) under valgrind: 75 | $ gcc hello.c -wrapper valgrind 76 | 77 | .. note:: 78 | 79 | For good results under valgrind, it's best to configure your build 80 | of gcc with :option:`--enable-valgrind-annotations`, which automatically 81 | suppresses various known false positives. 82 | 83 | Support scripts for ``gdb`` 84 | --------------------------- 85 | 86 | The source tree contains two support scripts that significantly improve 87 | the debugging experience within ``gdb``, but some setup is required. 88 | 89 | ``gcc/configure`` (from ``configure.ac``) automatically generates a 90 | ``.gdbinit`` within the ``gcc`` subdirectory of the build directory, 91 | and when run by ``gdb``. 92 | 93 | This should be automatically detected and run by gdb. However, you may see 94 | a message from gdb of the form:: 95 | 96 | "path-to-build/gcc/.gdbinit" auto-loading has been declined by your `auto-load safe-path' 97 | 98 | as a protection against untrustworthy python scripts. See 99 | http://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html 100 | 101 | The fix is to mark the paths of the ``build/gcc`` directory as trustworthy. 102 | An easy way to do so is by adding the following to your ``~/.gdbinit`` script:: 103 | 104 | add-auto-load-safe-path /absolute/path/to/build/gcc 105 | 106 | for the build directories for your various checkouts of gcc. 107 | 108 | If it's working, you should see the message:: 109 | 110 | Successfully loaded GDB hooks for GCC 111 | 112 | as gdb starts up. 113 | 114 | The generated ``.gdbinit`` script loads two files: 115 | 116 | (a) `gcc/gdbinit.in `_ 117 | contains useful commands in ``gdb``'s own language, sets up 118 | useful breakpoints, and skipping of some very heavily-used inline 119 | functions. 120 | 121 | (b) `gcc/gdbhooks.py `_ 122 | injects useful Python code into gdb, for pretty-printing important 123 | data types. 124 | 125 | See the links above for more information. 126 | 127 | 128 | Why can't I find option-related variables in the debugger? 129 | ---------------------------------------------------------- 130 | 131 | Consider this line of code: 132 | 133 | .. code-block:: c++ 134 | 135 | return optimize > 0 && flag_forward_propagate; 136 | 137 | It might be reasonable to presume that these are variables that can be 138 | inspected in the debugger, but, despite the lack of block capitals, 139 | they're actually macros, and hence the "obvious" approach fails:: 140 | 141 | (gdb) print optimize 142 | No symbol "optimize" in current context. 143 | (gdb) print flag_forward_propagate 144 | No symbol "flag_forward_propagate" in current context. 145 | 146 | They're autogenerated preprocessor macros: during the build, 147 | ``BUILDDIR/gcc/options.h`` is written out, and contains code like this: 148 | 149 | .. code-block:: c++ 150 | 151 | #ifdef GENERATOR_FILE 152 | extern int optimize; 153 | #else 154 | int x_optimize; 155 | #define optimize global_options.x_optimize 156 | #endif 157 | 158 | and: 159 | 160 | .. code-block:: c++ 161 | 162 | #ifdef GENERATOR_FILE 163 | extern int flag_forward_propagate; 164 | #else 165 | int x_flag_forward_propagate; 166 | #define flag_forward_propagate global_options.x_flag_forward_propagate 167 | #endif 168 | 169 | Hence they're only variables when ``GENERATOR_FILE`` is defined (when 170 | building certain build-time support files); for the common case of 171 | the compiler and driver, these are actually fields within the 172 | ``global_options`` struct, with a ``x_`` prefix. 173 | 174 | Hence to read these values when debugging you would use the following:: 175 | 176 | (gdb) print global_options.x_optimize 177 | $1 = 3 178 | (gdb) print global_options.x_flag_forward_propagate 179 | $2 = 1 180 | 181 | reflecting that, in this case, :option:`-O3` was supplied on the 182 | command-line, and that it implicitly enabled :option:`-fforward-propagate`. 183 | 184 | 185 | How do I find where a particular `tree` was created? 186 | ---------------------------------------------------- 187 | 188 | If you have a `tree` node, you can put a watchpoint on the memory location 189 | representing its tree code. This will trigger as the tree node 190 | is created, which can be helpful for detecting, say, where in a front-end 191 | something is built. The memory location might be modified a few times 192 | before the node is allocated. 193 | 194 | For example, when tracking down where a particular ``IDENTIFIER_NODE`` 195 | was built (to fix a `bogus suggestion in the C++ frontend 196 | `_):: 197 | 198 | (gdb) p suggestion 199 | $5 = 200 | 201 | (gdb) p suggestion->base.code 202 | $6 = IDENTIFIER_NODE 203 | 204 | Here I put the watchpoint on it:: 205 | 206 | (gdb) watch -l suggestion->base.code 207 | Hardware watchpoint 10: -location suggestion->base.code 208 | 209 | On re-running, it takes a few writes before we hit the creation of 210 | the ``IDENTIFIER_NODE``:: 211 | 212 | (gdb) run 213 | The program being debugged has been started already. 214 | Start it from the beginning? (y or n) y 215 | 216 | [...snip...] 217 | Hardware watchpoint 10: -location suggestion->base.code 218 | 219 | Old value = 220 | New value = 2947526575 221 | memset () at ../sysdeps/x86_64/memset.S:69 222 | 69 movdqu %xmm8, -16(%rdi,%rdx) 223 | (gdb) cont 224 | Continuing. 225 | Hardware watchpoint 10: -location suggestion->base.code 226 | 227 | Old value = 2947526575 228 | New value = ERROR_MARK 229 | memset () at ../sysdeps/x86_64/memset.S:69 230 | 69 movdqu %xmm8, -16(%rdi,%rdx) 231 | (gdb) cont 232 | Continuing. 233 | Hardware watchpoint 10: -location suggestion->base.code 234 | 235 | Old value = ERROR_MARK 236 | New value = IDENTIFIER_NODE 237 | make_node (code=IDENTIFIER_NODE) at ../../src/gcc/tree.c:1035 238 | 1035 switch (type) 239 | 240 | At this point, we can examine the backtrace and see what created the node. 241 | 242 | Similar techniques can be used to track down where gimple statements 243 | are created, and so on. 244 | 245 | 246 | Where in the user's source is this `location_t`? 247 | ------------------------------------------------ 248 | 249 | GCC uses `location_t` to track locations in the user's source code. 250 | This data type is effectively a key into a database, and due to the need 251 | to pack information into a limited number of bits is encoded in a 252 | non-trivial way. 253 | 254 | A handy trick for debugging locations is to inject a call to `inform` 255 | in the debugger, which emits a `note` diagnostic at a particular 256 | `location_t`:: 257 | 258 | (gdb) call inform (loc, "") 259 | test.c: In function ‘fn_1’: 260 | test.c:15:7: note: 261 | 15 | if (flag) 262 | | ^~~~ 263 | 264 | A couple of caveats with this: 265 | 266 | * the diagnostics subsystem doesn't print the source code if it was the 267 | same location_t as the last time a diagnostic was emitted 268 | 269 | * the diagnostic subsystem is not re-entrant, so you can't use this when 270 | you're inside the diagnostic emission code 271 | 272 | TODO: 273 | 274 | * howto: stepping through the compiler, stepping through a pass 275 | 276 | * talk about dumpfiles also 277 | -------------------------------------------------------------------------------- /binaries-and-processes.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2022-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Binaries and processes 19 | ---------------------- 20 | 21 | Given this trivial C program as :file:`hello.c`:: 22 | 23 | #include 24 | int main () 25 | { 26 | printf ("hello world\n"); 27 | return 0; 28 | } 29 | 30 | what happens when you compile it with GCC? 31 | 32 | If we run this command line: 33 | 34 | .. code-block:: sh 35 | 36 | # compile hello.c to an executable named "hello" 37 | $ gcc hello.c -o hello 38 | 39 | we end up with an executable: 40 | 41 | .. code-block:: sh 42 | 43 | $ ls 44 | hello hello.c 45 | 46 | which we can run: 47 | 48 | .. code-block:: sh 49 | 50 | $ ./hello 51 | hello world 52 | 53 | but a lot has happened "under the hood". 54 | 55 | The :program:`gcc` binary is actually just a relatively small "driver" 56 | program. It looks at what inputs you have provided, and what output you 57 | have asked for, and tries to figure out what to do. 58 | 59 | In this case we have a C source file as input (:file:`hello.c`), and 60 | an executable as output. 61 | 62 | The :program:`gcc` driver "knows" that it can compile :file:`.c` files 63 | to assembler by invoking GCC's C compiler, which is a binary called 64 | :file:`cc1`. This will take :file:`hello.c` as input, and generate 65 | an assembler file with a :file:`.s` suffix. The driver will then 66 | invoke the assembler on that :file:`.s` file, generating an object file. 67 | This is a binary file format, containing machine code and metadata, 68 | typically in a file format called ELF. However, this :file:`.o` can't 69 | be run directly; it needs to go through the linker, which will generate 70 | the final executable that can be run (also an ELF file). 71 | 72 | In diagram form:: 73 | 74 | cc1 as linker 75 | hello.c -----> tmp.s ----> tmp.o --------> "hello" executable 76 | 77 | We can investigate by adding the :option:`-v` option, which makes :program:`gcc` 78 | print copious amounts of information to stderr. 79 | 80 | Here's the output when I run it (your output may look a little 81 | different): 82 | 83 | .. code-block:: 84 | 85 | $ gcc hello.c -o hello -v 86 | Using built-in specs. 87 | COLLECT_GCC=gcc 88 | COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-redhat-linux/10/lto-wrapper 89 | OFFLOAD_TARGET_NAMES=nvptx-none 90 | OFFLOAD_TARGET_DEFAULT=1 91 | Target: x86_64-redhat-linux 92 | Configured with: ../configure --enable-bootstrap --enable-languages=c,c++,fortran,objc,obj-c++,ada,go,d,lto --prefix=/usr --mandir=/usr/share/man --infodir=/usr/share/info --with-bugurl=http://bugzilla.redhat.com/bugzilla --enable-shared --enable-threads=posix --enable-checking=release --enable-multilib --with-system-zlib --enable-__cxa_atexit --disable-libunwind-exceptions --enable-gnu-unique-object --enable-linker-build-id --with-gcc-major-version-only --with-linker-hash-style=gnu --enable-plugin --enable-initfini-array --with-isl --enable-offload-targets=nvptx-none --without-cuda-driver --enable-gnu-indirect-function --enable-cet --with-tune=generic --with-arch_32=i686 --build=x86_64-redhat-linux 93 | Thread model: posix 94 | Supported LTO compression algorithms: zlib zstd 95 | gcc version 10.3.1 20210422 (Red Hat 10.3.1-1) (GCC) 96 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 97 | /usr/libexec/gcc/x86_64-redhat-linux/10/cc1 -quiet -v hello.c -quiet -dumpbase hello.c -mtune=generic -march=x86-64 -auxbase hello -version -o /tmp/cckqYOSJ.s 98 | GNU C17 (GCC) version 10.3.1 20210422 (Red Hat 10.3.1-1) (x86_64-redhat-linux) 99 | compiled by GNU C version 10.3.1 20210422 (Red Hat 10.3.1-1), GMP version 6.2.0, MPFR version 4.1.0-p9, MPC version 1.1.0, isl version isl-0.16.1-GMP 100 | 101 | GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 102 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-redhat-linux/10/include-fixed" 103 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-redhat-linux/10/../../../../x86_64-redhat-linux/include" 104 | #include "..." search starts here: 105 | #include <...> search starts here: 106 | /usr/lib/gcc/x86_64-redhat-linux/10/include 107 | /usr/local/include 108 | /usr/include 109 | End of search list. 110 | GNU C17 (GCC) version 10.3.1 20210422 (Red Hat 10.3.1-1) (x86_64-redhat-linux) 111 | compiled by GNU C version 10.3.1 20210422 (Red Hat 10.3.1-1), GMP version 6.2.0, MPFR version 4.1.0-p9, MPC version 1.1.0, isl version isl-0.16.1-GMP 112 | 113 | GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 114 | Compiler executable checksum: b30993865ac347030daf9d56a2db69cd 115 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 116 | as -v --64 -o /tmp/ccXNu6jN.o /tmp/cckqYOSJ.s 117 | GNU assembler version 2.35 (x86_64-redhat-linux) using BFD version version 2.35-18.fc33 118 | COMPILER_PATH=/usr/libexec/gcc/x86_64-redhat-linux/10/:/usr/libexec/gcc/x86_64-redhat-linux/10/:/usr/libexec/gcc/x86_64-redhat-linux/:/usr/lib/gcc/x86_64-redhat-linux/10/:/usr/lib/gcc/x86_64-redhat-linux/ 119 | LIBRARY_PATH=/usr/lib/gcc/x86_64-redhat-linux/10/:/usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/:/lib/../lib64/:/usr/lib/../lib64/:/usr/lib/gcc/x86_64-redhat-linux/10/../../../:/lib/:/usr/lib/ 120 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 121 | /usr/libexec/gcc/x86_64-redhat-linux/10/collect2 -plugin /usr/libexec/gcc/x86_64-redhat-linux/10/liblto_plugin.so -plugin-opt=/usr/libexec/gcc/x86_64-redhat-linux/10/lto-wrapper -plugin-opt=-fresolution=/tmp/cchv3sYK.res -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s -plugin-opt=-pass-through=-lc -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s --build-id --no-add-needed --eh-frame-hdr --hash-style=gnu -m elf_x86_64 -dynamic-linker /lib64/ld-linux-x86-64.so.2 -o hello /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crt1.o /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crti.o /usr/lib/gcc/x86_64-redhat-linux/10/crtbegin.o -L/usr/lib/gcc/x86_64-redhat-linux/10 -L/usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64 -L/lib/../lib64 -L/usr/lib/../lib64 -L/usr/lib/gcc/x86_64-redhat-linux/10/../../.. /tmp/ccXNu6jN.o -lgcc --push-state --as-needed -lgcc_s --pop-state -lc -lgcc --push-state --as-needed -lgcc_s --pop-state /usr/lib/gcc/x86_64-redhat-linux/10/crtend.o /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crtn.o 122 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 123 | 124 | That's a lot of text. Let's break it down a bit to see what's going on. 125 | 126 | Immediately below the command-line I typed, :program:`gcc` has emitted 127 | some version information about itself, and how it has been configured: 128 | 129 | .. code-block:: 130 | 131 | $ gcc hello.c -o hello -v 132 | Using built-in specs. 133 | COLLECT_GCC=gcc 134 | COLLECT_LTO_WRAPPER=/usr/libexec/gcc/x86_64-redhat-linux/10/lto-wrapper 135 | OFFLOAD_TARGET_NAMES=nvptx-none 136 | OFFLOAD_TARGET_DEFAULT=1 137 | Target: x86_64-redhat-linux 138 | Configured with: ../configure --enable-bootstrap --enable-languages=c,c++,fortran,objc,obj-c++,ada,go,d,lto --prefix=/usr --mandir=/usr/share/man --infodir=/usr/share/info --with-bugurl=http://bugzilla.redhat.com/bugzilla --enable-shared --enable-threads=posix --enable-checking=release --enable-multilib --with-system-zlib --enable-__cxa_atexit --disable-libunwind-exceptions --enable-gnu-unique-object --enable-linker-build-id --with-gcc-major-version-only --with-linker-hash-style=gnu --enable-plugin --enable-initfini-array --with-isl --enable-offload-targets=nvptx-none --without-cuda-driver --enable-gnu-indirect-function --enable-cet --with-tune=generic --with-arch_32=i686 --build=x86_64-redhat-linux 139 | Thread model: posix 140 | Supported LTO compression algorithms: zlib zstd 141 | gcc version 10.3.1 20210422 (Red Hat 10.3.1-1) (GCC) 142 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 143 | 144 | Next is the :program:`cc1` invocation: 145 | 146 | .. code-block:: sh 147 | 148 | /usr/libexec/gcc/x86_64-redhat-linux/10/cc1 -quiet -v hello.c -quiet -dumpbase hello.c -mtune=generic -march=x86-64 -auxbase hello -version -o /tmp/cckqYOSJ.s 149 | 150 | That command-line is very long, so let's reformat it to make it easier 151 | to see what's going on: 152 | 153 | .. code-block:: sh 154 | 155 | /usr/libexec/gcc/x86_64-redhat-linux/10/cc1 \ 156 | -quiet \ 157 | -v \ 158 | hello.c \ 159 | -quiet \ 160 | -dumpbase hello.c \ 161 | -mtune=generic \ 162 | -march=x86-64 \ 163 | -auxbase hello \ 164 | -version \ 165 | -o /tmp/cckqYOSJ.s 166 | 167 | Looking at the above options in turn, starting with the :program:`cc1` invocation: 168 | 169 | We can see that the :program:`cc1` binary isn't in the :envvar:`PATH` 170 | but is hidden away in a separate directory 171 | (:file:`/usr/libexec/gcc/x86_64-redhat-linux/10/`) that the 172 | :program:`gcc` driver knows to use. 173 | 174 | :option:`-quiet`: 175 | 176 | This option was supplied by the driver twice: without it the compiler 177 | emits debugging messages to stderr about what it's doing, which can be 178 | handy when debugging it directly. 179 | 180 | :option:`-v`: 181 | 182 | This is passed on from the :program:`gcc` invocation to its invocation 183 | of :program:`cc1`, so :program:`cc1` will, in turn, emit lots of 184 | verbose information to stderr about what it is doing. 185 | 186 | :file:`hello.c`: 187 | 188 | tells :program:`cc1` which source file to compile. 189 | 190 | :option:`-dumpbase hello.c` 191 | 192 | tells :program:`cc1` that when it creates any dump files, it should 193 | use `hello.c` as the base for their filenames. It won't create any 194 | dump files by default, but we'll do that below. 195 | 196 | :option:`-mtune=generic` and :option:`-march=x86-64` 197 | 198 | are both architecture-specific options, documented in 199 | https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html 200 | 201 | They affect the kind of machine code that the compiler will generate. 202 | 203 | :option:`-mtune=generic` for x86 means "try to tune the performance 204 | of the generated code for a blend of popular x86 processors". 205 | 206 | :option:`-march=x86-64` for x86 means generate code for a generic x86 207 | CPU with 64-bit extensions 208 | 209 | :option:`-auxbase hello`: 210 | 211 | was an undocumented option that later releases of GCC don't use 212 | anymore. 213 | 214 | :option:`-version`: 215 | 216 | makes :program:`cc1` emit version information to stderr 217 | 218 | :option:`-o /tmp/cckqYOSJ.s`: 219 | 220 | tells :program:`cc1` to use :file:`/tmp/cckqYOSJ.s` as the output file 221 | when writing the generated assembler. 222 | 223 | The precise temporary file will change from invocation to invocation, 224 | and the :program:`gcc` driver will delete its temporary files when its 225 | done. If you're exploring how gcc works, or debugging, you can use 226 | the :option:`-save-temps` option to tell :program:`gcc` to keep these 227 | intermediate files around. 228 | 229 | You might see slightly different options; you can see the full 230 | documentation for GCC options at 231 | https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html (though that can 232 | get overwhelming). 233 | 234 | Given that :program:`gcc` passed on the :option:`-v` option to 235 | :program:`cc1`, the next thing on stderr is the verbose output from 236 | :program:`cc1`. This mainly consists of version and configuration 237 | information: 238 | 239 | .. code-block:: 240 | 241 | GNU C17 (GCC) version 10.3.1 20210422 (Red Hat 10.3.1-1) (x86_64-redhat-linux) 242 | compiled by GNU C version 10.3.1 20210422 (Red Hat 10.3.1-1), GMP version 6.2.0, MPFR version 4.1.0-p9, MPC version 1.1.0, isl version isl-0.16.1-GMP 243 | 244 | GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 245 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-redhat-linux/10/include-fixed" 246 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-redhat-linux/10/../../../../x86_64-redhat-linux/include" 247 | #include "..." search starts here: 248 | #include <...> search starts here: 249 | /usr/lib/gcc/x86_64-redhat-linux/10/include 250 | /usr/local/include 251 | /usr/include 252 | End of search list. 253 | GNU C17 (GCC) version 10.3.1 20210422 (Red Hat 10.3.1-1) (x86_64-redhat-linux) 254 | compiled by GNU C version 10.3.1 20210422 (Red Hat 10.3.1-1), GMP version 6.2.0, MPFR version 4.1.0-p9, MPC version 1.1.0, isl version isl-0.16.1-GMP 255 | 256 | GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 257 | Compiler executable checksum: b30993865ac347030daf9d56a2db69cd 258 | 259 | We'll go into more detail about what happens in :program:`cc1` in a 260 | later section. 261 | 262 | Next comes the invocation of :program:`as`, the assembler: 263 | 264 | .. code-block:: sh 265 | 266 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 267 | as -v --64 -o /tmp/ccXNu6jN.o /tmp/cckqYOSJ.s 268 | GNU assembler version 2.35 (x86_64-redhat-linux) using BFD version version 2.35-18.fc33 269 | 270 | This is much simpler, where the :program:`gcc` driver invokes :program:`as` with: 271 | 272 | .. code-block:: sh 273 | 274 | as -v --64 -o /tmp/ccXNu6jN.o /tmp/cckqYOSJ.s 275 | 276 | essentially merely telling it the input :file:`.s` file, the output 277 | :file:`.o` file, and a couple of options. 278 | 279 | Next comes the linker invocation; in this case :program:`gcc` driver invokes :program:`collect2`: 280 | 281 | .. code-block:: sh 282 | 283 | COMPILER_PATH=/usr/libexec/gcc/x86_64-redhat-linux/10/:/usr/libexec/gcc/x86_64-redhat-linux/10/:/usr/libexec/gcc/x86_64-redhat-linux/:/usr/lib/gcc/x86_64-redhat-linux/10/:/usr/lib/gcc/x86_64-redhat-linux/ 284 | LIBRARY_PATH=/usr/lib/gcc/x86_64-redhat-linux/10/:/usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/:/lib/../lib64/:/usr/lib/../lib64/:/usr/lib/gcc/x86_64-redhat-linux/10/../../../:/lib/:/usr/lib/ 285 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 286 | /usr/libexec/gcc/x86_64-redhat-linux/10/collect2 -plugin /usr/libexec/gcc/x86_64-redhat-linux/10/liblto_plugin.so -plugin-opt=/usr/libexec/gcc/x86_64-redhat-linux/10/lto-wrapper -plugin-opt=-fresolution=/tmp/cchv3sYK.res -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s -plugin-opt=-pass-through=-lc -plugin-opt=-pass-through=-lgcc -plugin-opt=-pass-through=-lgcc_s --build-id --no-add-needed --eh-frame-hdr --hash-style=gnu -m elf_x86_64 -dynamic-linker /lib64/ld-linux-x86-64.so.2 -o hello /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crt1.o /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crti.o /usr/lib/gcc/x86_64-redhat-linux/10/crtbegin.o -L/usr/lib/gcc/x86_64-redhat-linux/10 -L/usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64 -L/lib/../lib64 -L/usr/lib/../lib64 -L/usr/lib/gcc/x86_64-redhat-linux/10/../../.. /tmp/ccXNu6jN.o -lgcc --push-state --as-needed -lgcc_s --pop-state -lc -lgcc --push-state --as-needed -lgcc_s --pop-state /usr/lib/gcc/x86_64-redhat-linux/10/crtend.o /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crtn.o 287 | COLLECT_GCC_OPTIONS='-o' 'hello' '-v' '-mtune=generic' '-march=x86-64' 288 | 289 | The command the driver uses to invoke the linker is over 1000 characters 290 | long. We can reformat it to make it more approachable, but it's still 291 | rather intimidating: 292 | 293 | .. code-block:: sh 294 | 295 | /usr/libexec/gcc/x86_64-redhat-linux/10/collect2 \ 296 | -plugin /usr/libexec/gcc/x86_64-redhat-linux/10/liblto_plugin.so \ 297 | -plugin-opt=/usr/libexec/gcc/x86_64-redhat-linux/10/lto-wrapper \ 298 | -plugin-opt=-fresolution=/tmp/cchv3sYK.res \ 299 | -plugin-opt=-pass-through=-lgcc \ 300 | -plugin-opt=-pass-through=-lgcc_s \ 301 | -plugin-opt=-pass-through=-lc \ 302 | -plugin-opt=-pass-through=-lgcc \ 303 | -plugin-opt=-pass-through=-lgcc_s \ 304 | --build-id \ 305 | --no-add-needed \ 306 | --eh-frame-hdr \ 307 | --hash-style=gnu \ 308 | -m elf_x86_64 \ 309 | -dynamic-linker \ 310 | /lib64/ld-linux-x86-64.so.2 \ 311 | -o hello \ 312 | /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crt1.o \ 313 | /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crti.o \ 314 | /usr/lib/gcc/x86_64-redhat-linux/10/crtbegin.o \ 315 | -L/usr/lib/gcc/x86_64-redhat-linux/10 \ 316 | -L/usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64 \ 317 | -L/lib/../lib64 \ 318 | -L/usr/lib/../lib64 \ 319 | -L/usr/lib/gcc/x86_64-redhat-linux/10/../../.. \ 320 | /tmp/ccXNu6jN.o \ 321 | -lgcc \ 322 | --push-state \ 323 | --as-needed \ 324 | -lgcc_s \ 325 | --pop-state \ 326 | -lc \ 327 | -lgcc \ 328 | --push-state 329 | --as-needed \ 330 | -lgcc_s \ 331 | --pop-state \ 332 | /usr/lib/gcc/x86_64-redhat-linux/10/crtend.o \ 333 | /usr/lib/gcc/x86_64-redhat-linux/10/../../../../lib64/crtn.o 334 | 335 | We'll skip the details for now so that we can focus on :program:`cc1` 336 | in the next section, but perhaps the most important options are 337 | :option:`-o hello` specifying the output file, and 338 | :option:`/tmp/ccXNu6jN.o` specifying the file that the assembler just 339 | emitted, this time as an input file to the linker (containing the user's 340 | code built from :file:`hello.c`). It's also linking in various support 341 | libraries needed by an executable binary. 342 | -------------------------------------------------------------------------------- /COPYING3: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /inside-cc1.rst: -------------------------------------------------------------------------------- 1 | .. Copyright (C) 2016-2023 Free Software Foundation, Inc. 2 | Originally contributed by David Malcolm 3 | 4 | This is free software: you can redistribute it and/or modify it 5 | under the terms of the GNU General Public License as published by 6 | the Free Software Foundation, either version 3 of the License, or 7 | (at your option) any later version. 8 | 9 | This program is distributed in the hope that it will be useful, but 10 | WITHOUT ANY WARRANTY; without even the implied warranty of 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 | General Public License for more details. 13 | 14 | You should have received a copy of the GNU General Public License 15 | along with this program. If not, see 16 | . 17 | 18 | Inside :program:`cc1` 19 | --------------------- 20 | 21 | GCC is a collection of compilers for different languages, which 22 | can generate code for a wide variety of different CPU architectures. 23 | 24 | GCC currently supports 10 source languages, and 55 target CPU 25 | architectures. We don't want to have to write 550 different compilers, 26 | so, as is common, GCC is structured into three parts: 27 | 28 | * source language "front ends" - one for each source language, taking 29 | the source language as input, using it to generating an "intermediate 30 | represention" (IR) of the user's code in a language-independent 31 | internal format 32 | 33 | * target-specific "back ends" - one for each target, taking the intermediate 34 | representation as input, and generating assembler for that target 35 | 36 | * the so-called "middle end", sitting between these, which optimizes the 37 | code, so that the back end has better code to work with 38 | 39 | So :program:`cc1` built for ``x86_64`` has the C frontend, the shared 40 | optimizing code, and the x86_64 backend:: 41 | 42 | +-----+ 43 | +-| cc1 |--------------------------------------------------+ 44 | | +-----+ | 45 | | | 46 | | C frontend Optimizer x86_64 backend | 47 | C source ====+==============> IR =============> IR ===================+==> x86_64 asm 48 | | | 49 | +----------------------------------------------------------+ 50 | 51 | Sadly the above picture is an idealized picture, in that the code is 52 | rather messier than that in practice. It's also over-simplified, in 53 | that GCC actually has several intermediate representations, which we'll talk 54 | about in detail below. 55 | 56 | * if you're interested in adding new warnings to GCC, you'll probably 57 | want to just look at the frontends for now, and to merely skim the 58 | sections below. 59 | 60 | * if you want to make GCC generate better code, you'll want to look at 61 | the middle-end and backends, and find out more about gcc's intermediate 62 | representations by reading the section below 63 | 64 | * if you're interested in adding support to GCC for a new kind of CPU, 65 | you'll want to look mostly at the backend/RTL sections below 66 | 67 | 68 | How does :program:`cc1` turn C into assembler? 69 | ********************************************** 70 | 71 | When figuring out how the compiler works, it's best to start with a really 72 | simple source file - in particular, one with doesn't ``#include`` any 73 | header files. Our earlier example used :file:``, so let's make 74 | an even simpler :file:`test.c`: 75 | 76 | .. code-block:: c 77 | 78 | int test (int a, int b, int c, int d) 79 | { 80 | if (a) 81 | return (b - c) * d; 82 | else 83 | return (c - b) * d; 84 | } 85 | 86 | Compiling it to assembler, with some optimization (:option:`-O2`) and 87 | enabling verbose assembler output (:option:`-fverbose-asm`): 88 | 89 | .. code-block:: sh 90 | 91 | $ gcc -S test.c -O2 -fverbose-asm 92 | 93 | gives this :file:`test.s`: 94 | 95 | .. code-block:: asm 96 | 97 | .file "test.c" 98 | ; ...omitting dump of options for brevity... 99 | .text 100 | .p2align 4 101 | .globl test 102 | .type test, @function 103 | test: 104 | .LFB0: 105 | .cfi_startproc 106 | # test.c:2: { 107 | movl %ecx, %eax # tmp97, d 108 | # test.c:3: if (a) 109 | testl %edi, %edi # tmp94 110 | je .L2 #, 111 | # test.c:4: return (b - c) * d; 112 | subl %edx, %esi # c, tmp89 113 | # test.c:4: return (b - c) * d; 114 | imull %esi, %eax # tmp89, 115 | ret 116 | .p2align 4,,10 117 | .p2align 3 118 | .L2: 119 | # test.c:6: return (c - b) * d; 120 | subl %esi, %edx # b, tmp90 121 | # test.c:6: return (c - b) * d; 122 | imull %edx, %eax # tmp90, 123 | # test.c:7: } 124 | ret 125 | .cfi_endproc 126 | .LFE0: 127 | .size test, .-test 128 | .ident "GCC: (GNU) 10.3.1 20210422 (Red Hat 10.3.1-1)" 129 | .section .note.GNU-stack,"",@progbits 130 | 131 | where :program:`cc1` has converted the C code into a pair of 132 | subtractions (:code:`subl`), and a pair of multiplies (:code:`imull`) 133 | that populate the ``%eax`` register, used for the return value. 134 | 135 | You can see GCC's intermediate representations using GCC's dump options. If 136 | we add :option:`-fdump-tree-all -fdump-ipa-all -fdump-rtl-all` to the 137 | above command line, giving: 138 | 139 | .. code-block:: sh 140 | 141 | gcc -S test.c -O2 -fverbose-asm -fdump-tree-all -fdump-ipa-all -fdump-rtl-all 142 | 143 | then these dump options lead :program:`cc1` to emit *many* dump files 144 | (192 in the following example): 145 | 146 | .. code-block:: sh 147 | 148 | $ ls 149 | test.c test.c.101t.alias test.c.238r.vregs 150 | test.c.000i.cgraph test.c.102t.retslot test.c.239r.into_cfglayout 151 | test.c.000i.ipa-clones test.c.103t.fre3 test.c.240r.jump 152 | test.c.000i.type-inheritance test.c.104t.mergephi2 test.c.241r.subreg1 153 | test.c.004t.original test.c.105t.thread1 test.c.242r.dfinit 154 | test.c.005t.gimple test.c.106t.vrp1 test.c.243r.cse1 155 | test.c.007t.omplower test.c.107t.dce2 test.c.244r.fwprop1 156 | test.c.008t.lower test.c.108t.stdarg test.c.245r.cprop1 157 | test.c.011t.eh test.c.109t.cdce test.c.246r.pre 158 | test.c.013t.cfg test.c.110t.cselim test.c.248r.cprop2 159 | test.c.015t.ompexp test.c.111t.copyprop1 test.c.251r.ce1 160 | test.c.018i.visibility test.c.112t.ifcombine test.c.252r.reginfo 161 | test.c.019i.build_ssa_passes test.c.113t.mergephi3 test.c.253r.loop2 162 | test.c.020t.fixup_cfg1 test.c.114t.phiopt2 test.c.254r.loop2_init 163 | test.c.021t.ssa test.c.115t.tailr2 test.c.255r.loop2_invariant 164 | test.c.023t.nothrow test.c.116t.ch2 test.c.258r.loop2_done 165 | test.c.024i.opt_local_passes test.c.117t.cplxlower1 test.c.261r.cprop3 166 | test.c.025t.fixup_cfg2 test.c.118t.sra test.c.262r.stv1 167 | test.c.026t.local-fnsummary1 test.c.119t.thread2 test.c.263r.cse2 168 | test.c.027t.einline test.c.120t.dom2 test.c.264r.dse1 169 | test.c.028t.early_optimizations test.c.121t.copyprop2 test.c.265r.fwprop2 170 | test.c.029t.objsz1 test.c.122t.isolate-paths test.c.267r.init-regs 171 | test.c.030t.ccp1 test.c.123t.dse2 test.c.268r.ud_dce 172 | test.c.031t.forwprop1 test.c.124t.reassoc1 test.c.269r.combine 173 | test.c.032t.ethread test.c.125t.dce3 test.c.271r.stv2 174 | test.c.033t.esra test.c.126t.forwprop3 test.c.272r.ce2 175 | test.c.034t.ealias test.c.127t.phiopt3 test.c.273r.jump_after_combine 176 | test.c.035t.fre1 test.c.128t.ccp3 test.c.274r.bbpart 177 | test.c.036t.evrp test.c.129t.sincos test.c.275r.outof_cfglayout 178 | test.c.037t.mergephi1 test.c.130t.bswap test.c.276r.split1 179 | test.c.038t.dse1 test.c.131t.laddress test.c.277r.subreg3 180 | test.c.039t.cddce1 test.c.132t.lim2 test.c.279r.mode_sw 181 | test.c.040t.phiopt1 test.c.133t.walloca2 test.c.280r.asmcons 182 | test.c.041t.tailr1 test.c.134t.pre test.c.285r.ira 183 | test.c.042t.switchconv test.c.135t.sink test.c.286r.reload 184 | test.c.044t.profile_estimate test.c.139t.dce4 test.c.288r.postreload 185 | test.c.045t.local-pure-const1 test.c.140t.fix_loops test.c.290r.split2 186 | test.c.046t.fnsplit test.c.171t.no_loop test.c.291r.ree 187 | test.c.047t.release_ssa test.c.174t.veclower21 test.c.292r.cmpelim 188 | test.c.048t.local-fnsummary2 test.c.175t.switchlower1 test.c.293r.pro_and_epilogue 189 | test.c.049i.remove_symbols test.c.177t.reassoc2 test.c.294r.dse2 190 | test.c.061i.targetclone test.c.178t.slsr test.c.295r.csa 191 | test.c.065i.free-fnsummary1 test.c.181t.fre4 test.c.296r.jump2 192 | test.c.071i.whole-program test.c.182t.thread3 test.c.297r.compgotos 193 | test.c.072i.profile_estimate test.c.183t.dom3 test.c.299r.peephole2 194 | test.c.073i.icf test.c.184t.strlen1 test.c.300r.ce3 195 | test.c.074i.devirt test.c.185t.thread4 test.c.302r.cprop_hardreg 196 | test.c.075i.cp test.c.186t.vrp2 test.c.303r.rtl_dce 197 | test.c.076i.sra test.c.187t.copyprop5 test.c.304r.bbro 198 | test.c.079i.fnsummary test.c.188t.wrestrict test.c.305r.split3 199 | test.c.080i.inline test.c.189t.dse3 test.c.306r.sched2 200 | test.c.081i.pure-const test.c.190t.cddce3 test.c.308r.stack 201 | test.c.082i.free-fnsummary2 test.c.191t.forwprop4 test.c.309r.alignments 202 | test.c.083i.static-var test.c.192t.phiopt4 test.c.311r.mach 203 | test.c.084i.single-use test.c.193t.fab1 test.c.312r.barriers 204 | test.c.085i.comdats test.c.194t.widening_mul test.c.317r.shorten 205 | test.c.086i.materialize-all-clones test.c.195t.store-merging test.c.318r.nothrow 206 | test.c.088i.simdclone test.c.196t.tailc test.c.319r.dwarf2 207 | test.c.089t.fixup_cfg3 test.c.197t.dce7 test.c.320r.final 208 | test.c.094t.ccp2 test.c.198t.crited1 test.c.321r.dfinish 209 | test.c.096t.cunrolli test.c.200t.uncprop1 test.c.322t.statistics 210 | test.c.097t.backprop test.c.201t.local-pure-const2 test.c.323t.earlydebug 211 | test.c.098t.phiprop test.c.234t.nrv test.c.324t.debug 212 | test.c.099t.forwprop2 test.c.235t.optimized test.s 213 | test.c.100t.objsz2 test.c.237r.expand 214 | 215 | You'll see that they're of the form :file:`test.c.` followed by a 216 | 3 digit number, followed by "t", "i", or "r", then a suffix. 217 | 218 | The precise numbering and suffixes of dump files varies from release to 219 | release of GCC, and the subset that gets emitted will vary depending on 220 | the optimization option you choose - there were 192 in the above example 221 | (GCC 10, with :option:`-O2`). 222 | 223 | The dump files show the state of GCC's intermediate representation of the 224 | code at each "optimization pass". The numbering roughly corresponds to a 225 | time-ordering of the states within the compiler, so that e.g. 226 | :file:`test.c.004t.original` shows the initial state of the IR coming 227 | out of the C frontend, whilst :file:`test.c.320r.final` shows the 228 | final state as assembler is written out. Beware, though that the "i" 229 | dumps are numbered out-of-order relative to the other "t" and "r" passes. 230 | 231 | At a high level, :program:`cc1` works as follows. 232 | 233 | 234 | Lexing 235 | ****** 236 | 237 | First the input source is "tokenized", so that the stream of input 238 | characters is divided into a stream of tokens. This is called "lexing", 239 | and largely implemented in gcc in 240 | `libcpp `_ 241 | (which also implements the preprocessor - hence the name) so that e.g. 242 | we go from the sequence of characters: 243 | 244 | .. code-block:: none 245 | 246 | return (b - c) * d; 247 | 248 | to the sequence of tokens: 249 | 250 | .. code-block:: none 251 | 252 | CPP_KEYWORD(RID_RETURN) 253 | CPP_OPEN_PAREN 254 | CPP_NAME("b") 255 | CPP_MINUS 256 | CPP_NAME("c") 257 | CPP_CLOSE_PAREN 258 | CPP_MULT 259 | CPP_NAME("d") 260 | CPP_SEMICOLON 261 | 262 | annotated with information about where in the user's source they 263 | occurred. 264 | 265 | 266 | Parsing and the :c:type:`tree` type 267 | *********************************** 268 | 269 | Next the frontend parses the tokens from a flat stream into a tree-like 270 | structure reflecting the grammar of the language (or complains about 271 | syntax errors or type errors, and bails out). Most warnings are 272 | implemented here, so if you're interested in adding new warnings, this 273 | is the place to look. This stage uses gcc's :c:type:`tree` type. 274 | There may be frontend-specific kinds of node, in the tree but the 275 | frontend will convert these to a generic form, 276 | so that after each frontend the middle end "sees" a tree 277 | representation that we call 278 | `generic `_ 279 | (unless the frontend gave up due to a sufficiently serious error in the 280 | user's code). 281 | 282 | You can see the "generic" representation in the 283 | :file:`test.c.004t.original` dump: 284 | 285 | .. code-block:: c 286 | 287 | ;; Function test (null) 288 | ;; enabled by -tree-original 289 | 290 | 291 | { 292 | if (a != 0) 293 | { 294 | return (b - c) * d; 295 | } 296 | else 297 | { 298 | return (c - b) * d; 299 | } 300 | } 301 | 302 | In this example, the dump of the tree IR closely resembles the 303 | original C code, but sometimes you will see control flow expressed 304 | via "goto" statements that go to numbered labels, and temporary 305 | variables introduced by the frontend. 306 | 307 | If we're running under the debugger (see :ref:`debugging`), we can see 308 | the tree for a function body like this:: 309 | 310 | (gdb) call debug_tree(fndecl->function_decl.saved_tree) 311 | > 315 | side-effects 316 | body 317 | side-effects 318 | arg:0 319 | arg:0 320 | arg:1 321 | test.c:3:7 start: test.c:3:7 finish: test.c:3:7> 322 | arg:1 323 | side-effects 324 | arg:0 325 | side-effects arg:0 326 | arg:1 327 | 328 | arg:0 329 | arg:0 arg:1 330 | test.c:4:15 start: test.c:4:12 finish: test.c:4:18> arg:1 331 | test.c:4:20 start: test.c:4:12 finish: test.c:4:22> 332 | test.c:4:20 start: test.c:4:12 finish: test.c:4:22> 333 | test.c:4:20 start: test.c:4:12 finish: test.c:4:22> 334 | arg:2 335 | side-effects 336 | arg:0 337 | side-effects arg:0 338 | arg:1 339 | 340 | arg:0 341 | arg:0 arg:1 342 | test.c:6:15 start: test.c:6:12 finish: test.c:6:18> arg:1 343 | test.c:6:20 start: test.c:6:12 finish: test.c:6:22> 344 | test.c:6:20 start: test.c:6:12 finish: test.c:6:22> 345 | test.c:6:20 start: test.c:6:12 finish: test.c:6:22> 346 | test.c:3:6 start: test.c:3:6 finish: test.c:3:6> 347 | block 349 | public static QI test.c:1:5 align:8 warn_if_not_align:0 context initial result arguments 350 | struct-function 0x7fffea3f9000>> 351 | test.c:2:1 start: test.c:2:1 finish: test.c:2:1> 352 | 353 | where for example: 354 | 355 | * `cond_expr` is the conditional expression, with three arguments: 356 | 357 | * `ne_expr` is a "not-equal expression" for ``a != 0`` 358 | 359 | * each `return_expr` is one of the two return expressions 360 | 361 | * `parm_decl` is a parameter declaration (such as ``a``) 362 | 363 | * `integer_cst` is an integer constant (as opposed to a cast), such as ``0`` 364 | 365 | 366 | gimple 367 | ****** 368 | 369 | The tree-based IR can contain arbitrarily-complicated nested 370 | expressions, which is relatively easy for the frontends to generate, but 371 | difficult for the optimizer to work with, so GCC almost immediately converts 372 | it into a form named "gimple", in which compound expressions such as: 373 | 374 | .. code-block:: c 375 | 376 | (b - c) * d 377 | 378 | get flattened into a series of assignments to temporary variables. We 379 | can see the initial form of the gimple in the :file:`test.c.005t.gimple` 380 | dump: 381 | 382 | .. code-block:: c 383 | 384 | test (int a, int b, int c, int d) 385 | { 386 | int D.1938; 387 | 388 | if (a != 0) goto ; else goto ; 389 | : 390 | _1 = b - c; 391 | D.1938 = d * _1; 392 | // predicted unlikely by early return (on trees) predictor. 393 | return D.1938; 394 | : 395 | _2 = c - b; 396 | D.1938 = d * _2; 397 | // predicted unlikely by early return (on trees) predictor. 398 | return D.1938; 399 | } 400 | 401 | Note how the if/else control flow has become "goto" statements, and how 402 | the "gimplifier" has flattened: 403 | 404 | .. code-block:: c 405 | 406 | (b - c) * d 407 | 408 | into assignments to two temporaries (named ``_1`` and ``D.1938``): 409 | 410 | .. code-block:: c 411 | 412 | _1 = b - c; 413 | D.1938 = d * _1; 414 | 415 | This gives us a sequence of gimple statements, some of which are labels, 416 | and some of which ``goto`` those labels. 417 | 418 | The official documentation on gimple is 419 | `here `_. 420 | 421 | 422 | gimple with a CFG 423 | ***************** 424 | 425 | Although some optimization passes do work on this "gimple with labels" 426 | representation, it is almost immediately converted to a Control Flow 427 | Graph (CFG), a directed graph of "basic blocks" - sequences of 428 | statements with no control flow, where the control flow is expressed 429 | as the edges between the basic blocks. This can be seen in the 430 | :file:`test.c.013t.cfg` dump: 431 | 432 | .. code-block:: c 433 | 434 | ;; Function test (test, funcdef_no=0, decl_uid=1933, cgraph_uid=1, symbol_order=0) 435 | 436 | ;; 1 loops found 437 | ;; 438 | ;; Loop 0 439 | ;; header 0, latch 1 440 | ;; depth 0, outer -1 441 | ;; nodes: 0 1 2 3 4 5 442 | ;; 2 succs { 3 4 } 443 | ;; 3 succs { 5 } 444 | ;; 4 succs { 5 } 445 | ;; 5 succs { 1 } 446 | test (int a, int b, int c, int d) 447 | { 448 | int D.1938; 449 | 450 | : 451 | if (a != 0) 452 | goto ; [INV] 453 | else 454 | goto ; [INV] 455 | 456 | : 457 | _1 = b - c; 458 | D.1938 = d * _1; 459 | // predicted unlikely by early return (on trees) predictor. 460 | goto ; [INV] 461 | 462 | : 463 | _2 = c - b; 464 | D.1938 = d * _2; 465 | // predicted unlikely by early return (on trees) predictor. 466 | 467 | : 468 | return D.1938; 469 | 470 | } 471 | 472 | You can see the basic blocks via e.g. the ```` headers. 473 | There is also now a single ``return`` statement from the function; the 474 | multiple ``return`` statements are now all expressed by assigning to a 475 | temporary (``D.1938``), and then a ``goto`` to the basic block 476 | containing the return statement. 477 | 478 | If you add the ``-graph`` suffix to the ``dump`` command line options: 479 | 480 | .. code-block:: sh 481 | 482 | $ gcc -S test.c -O2 -fverbose-asm \ 483 | -fdump-tree-all-graph -fdump-ipa-all-graph -fdump-rtl-all-graph 484 | 485 | then in addition to the dump files listed above, :program:`cc1` will 486 | also generate :file:`.dot` files, suitable for use with GraphViz. 487 | 488 | My favorite :file:`.dot` file viewer is 489 | `xdot `_, which shows 490 | :file:`test.c.013t.cfg.dot` as follows: 491 | 492 | .. image:: images/test.c.013t.cfg.dot-in-xdot.png 493 | 494 | which makes it easy to see the individual basic blocks, the statements 495 | within them, and the control flow linking them. 496 | 497 | 498 | gimple-SSA 499 | ********** 500 | 501 | After a few more optimization passes, the gimple-cfg IR is then 502 | converted to Static Single Assignment form (SSA). SSA form is commonly 503 | used inside compilers, as it makes many kinds of optimization much 504 | easier to implement. In SSA, every local variable is only ever assigned 505 | to once; if there are multiple assignments to a local variable, it gets 506 | split up into multiple versions. 507 | 508 | In our example, you can see the SSA form of the IR in :file:`test.c.021t.ssa`: 509 | 510 | .. code-block:: c 511 | 512 | ;; Function test (test, funcdef_no=0, decl_uid=1933, cgraph_uid=1, symbol_order=0) 513 | 514 | test (int a, int b, int c, int d) 515 | { 516 | int _1; 517 | int _2; 518 | int _3; 519 | int _8; 520 | int _9; 521 | 522 | : 523 | if (a_4(D) != 0) 524 | goto ; [INV] 525 | else 526 | goto ; [INV] 527 | 528 | : 529 | _1 = b_6(D) - c_5(D); 530 | _9 = d_7(D) * _1; 531 | // predicted unlikely by early return (on trees) predictor. 532 | goto ; [INV] 533 | 534 | : 535 | _2 = c_5(D) - b_6(D); 536 | _8 = d_7(D) * _2; 537 | // predicted unlikely by early return (on trees) predictor. 538 | 539 | : 540 | # _3 = PHI <_9(3), _8(4)> 541 | return _3; 542 | 543 | } 544 | 545 | and (in dot form) as :file:`test.c.021t.ssa.dot`: 546 | 547 | .. image:: images/test.c.021t.ssa.dot-in-xdot.png 548 | 549 | You can see that the single temporary ``D.1938`` from the earlier form 550 | of the IR has been split into three separate temporaries, where the two 551 | assignments: 552 | 553 | .. code-block:: c 554 | 555 | D.1938 = d * _1; 556 | 557 | and: 558 | 559 | .. code-block:: c 560 | 561 | D.1938 = d * _2; 562 | 563 | have now become these two assignments to separate temporaries: 564 | 565 | .. code-block:: c 566 | 567 | _9 = d_7(D) * _1; 568 | 569 | and: 570 | 571 | .. code-block:: c 572 | 573 | _8 = d_7(D) * _2; 574 | 575 | and at the point where control flow merges, we have a special construct 576 | called a "phi node" which assigns to the new temporary ``_3`` from either 577 | one of the ``_9`` or ``_8``, depending on whether control flow came 578 | from block 3 or block 4: 579 | 580 | .. code-block:: c 581 | 582 | # _3 = PHI <_9(3), _8(4)> 583 | 584 | You can see that the parameters ``b`` and ``c`` from the earlier form 585 | of the IR have also been numbered, so that the SSA form captures e.g. 586 | that we're accessing ``b_6(D)``, meaning version 6 of parameter ``b``, 587 | where the ``(D)`` means the initial value at the function entry: if 588 | code wrote to one of these parameters, the SSA form would have a 589 | different numbered version of it after the write. 590 | 591 | The official documentation for GCC's gimple-ssa form is 592 | `here `_. 593 | 594 | Once we're in gimple-SSA form, there are almost 200 optimization 595 | passes, which can be roughly divided into: 596 | 597 | * "intraprocedural" passes. These work on one function at a time. 598 | They have a "t" code in their dump file. For example, 599 | :file:`test.c.175t.switchlower` is the dump file for an optimization 600 | pass which converts gimple ``switch`` statements into lower-level 601 | gimple statements and control flow (which doesn't do anything in our 602 | example above, as it doesn't have any switch statements; try writing 603 | a simple C source file with a switch statement and see what it does) 604 | 605 | * "interprocedural passes" which consider all of the functions at once, 606 | such as which functions call which other functions. These have an 607 | "i" code in their dump file. An example is :file:`test.c.080i.inline` 608 | though given that our example has only one function, the 609 | interprocedural passes won't do anything useful 610 | 611 | The full set of optimizations passes can be see in GCC's source tree in 612 | the file 613 | `gcc/passes.def `_ 614 | 615 | After about 200 gimple optimizations passes, we're done with the 616 | gimple-SSA form; its final state can be seen in :file:`test.c.235t.optimized`: 617 | 618 | .. code-block:: c 619 | 620 | ;; Function test (test, funcdef_no=0, decl_uid=1933, cgraph_uid=1, symbol_order=0) 621 | 622 | test (int a, int b, int c, int d) 623 | { 624 | int _1; 625 | int _2; 626 | int _3; 627 | int _8; 628 | int _9; 629 | 630 | [local count: 1073741824]: 631 | if (a_4(D) != 0) 632 | goto ; [50.00%] 633 | else 634 | goto ; [50.00%] 635 | 636 | [local count: 536870913]: 637 | _1 = b_6(D) - c_5(D); 638 | _9 = _1 * d_7(D); 639 | goto ; [100.00%] 640 | 641 | [local count: 536870913]: 642 | _2 = c_5(D) - b_6(D); 643 | _8 = _2 * d_7(D); 644 | 645 | [local count: 1073741824]: 646 | # _3 = PHI <_9(3), _8(4)> 647 | return _3; 648 | 649 | } 650 | 651 | and :file:`test.c.235t.optimized.dot`: 652 | 653 | .. image:: images/test.c.235t.optimized.dot-in-xdot.png 654 | 655 | For our simple example, this hasn't been changed much since the initial 656 | conversion to SSA form; it's gained some estimates about how many times 657 | each basic block will be run (in lieu of real profiling data). 658 | 659 | 660 | RTL 661 | *** 662 | 663 | At this point, the gimple is converted to Register Transfer Language 664 | (RTL), a much lower-level representation of the code, which will allow 665 | us to eventually go all the way to assembler. The conversion happens 666 | in an optimization pass called "expand"; we can see the initial RTL form 667 | of the code in the :file:`test.c.237r.expand` dump file: 668 | 669 | .. code-block:: lisp 670 | 671 | ;; Function test (test, funcdef_no=0, decl_uid=1933, cgraph_uid=1, symbol_order=0) 672 | 673 | 674 | ;; Generating RTL for gimple basic block 2 675 | 676 | ;; Generating RTL for gimple basic block 3 677 | 678 | ;; Generating RTL for gimple basic block 4 679 | 680 | ;; Generating RTL for gimple basic block 5 681 | 682 | 683 | try_optimize_cfg iteration 1 684 | 685 | Merging block 3 into block 2... 686 | Merged blocks 2 and 3. 687 | Merged 2 and 3 without moving. 688 | Redirecting jump 14 from 6 to 7. 689 | Merging block 6 into block 5... 690 | Merged blocks 5 and 6. 691 | Merged 5 and 6 without moving. 692 | Removing jump 22. 693 | 694 | 695 | try_optimize_cfg iteration 2 696 | 697 | 698 | 699 | ;; 700 | ;; Full RTL generated for this function: 701 | ;; 702 | (note 1 0 7 NOTE_INSN_DELETED) 703 | (note 7 1 2 2 [bb 2] NOTE_INSN_BASIC_BLOCK) 704 | (insn 2 7 3 2 (set (reg/v:SI 85 [ a ]) 705 | (reg:SI 5 di [ a ])) "test.c":2:1 -1 706 | (nil)) 707 | (insn 3 2 4 2 (set (reg/v:SI 86 [ b ]) 708 | (reg:SI 4 si [ b ])) "test.c":2:1 -1 709 | (nil)) 710 | (insn 4 3 5 2 (set (reg/v:SI 87 [ c ]) 711 | (reg:SI 1 dx [ c ])) "test.c":2:1 -1 712 | (nil)) 713 | (insn 5 4 6 2 (set (reg/v:SI 88 [ d ]) 714 | (reg:SI 2 cx [ d ])) "test.c":2:1 -1 715 | (nil)) 716 | (note 6 5 9 2 NOTE_INSN_FUNCTION_BEG) 717 | (insn 9 6 10 2 (set (reg:CCZ 17 flags) 718 | (compare:CCZ (reg/v:SI 85 [ a ]) 719 | (const_int 0 [0]))) "test.c":3:6 -1 720 | (nil)) 721 | (jump_insn 10 9 11 2 (set (pc) 722 | (if_then_else (eq (reg:CCZ 17 flags) 723 | (const_int 0 [0])) 724 | (label_ref 16) 725 | (pc))) "test.c":3:6 -1 726 | (int_list:REG_BR_PROB 536870916 (nil)) 727 | -> 16) 728 | (note 11 10 12 4 [bb 4] NOTE_INSN_BASIC_BLOCK) 729 | (insn 12 11 13 4 (parallel [ 730 | (set (reg:SI 89) 731 | (minus:SI (reg/v:SI 86 [ b ]) 732 | (reg/v:SI 87 [ c ]))) 733 | (clobber (reg:CC 17 flags)) 734 | ]) "test.c":4:15 -1 735 | (nil)) 736 | (insn 13 12 14 4 (parallel [ 737 | (set (reg:SI 84 [ ]) 738 | (mult:SI (reg:SI 89) 739 | (reg/v:SI 88 [ d ]))) 740 | (clobber (reg:CC 17 flags)) 741 | ]) "test.c":4:20 -1 742 | (nil)) 743 | (jump_insn 14 13 15 4 (set (pc) 744 | (label_ref:DI 24)) "test.c":4:20 737 {jump} 745 | (nil) 746 | -> 24) 747 | (barrier 15 14 16) 748 | (code_label 16 15 17 5 2 (nil) [1 uses]) 749 | (note 17 16 18 5 [bb 5] NOTE_INSN_BASIC_BLOCK) 750 | (insn 18 17 19 5 (parallel [ 751 | (set (reg:SI 90) 752 | (minus:SI (reg/v:SI 87 [ c ]) 753 | (reg/v:SI 86 [ b ]))) 754 | (clobber (reg:CC 17 flags)) 755 | ]) "test.c":6:15 -1 756 | (nil)) 757 | (insn 19 18 24 5 (parallel [ 758 | (set (reg:SI 84 [ ]) 759 | (mult:SI (reg:SI 90) 760 | (reg/v:SI 88 [ d ]))) 761 | (clobber (reg:CC 17 flags)) 762 | ]) "test.c":6:20 -1 763 | (nil)) 764 | (code_label 24 19 27 7 1 (nil) [1 uses]) 765 | (note 27 24 25 7 [bb 7] NOTE_INSN_BASIC_BLOCK) 766 | (insn 25 27 26 7 (set (reg/i:SI 0 ax) 767 | (reg:SI 84 [ ])) "test.c":7:1 -1 768 | (nil)) 769 | (insn 26 25 0 7 (use (reg/i:SI 0 ax)) "test.c":7:1 -1 770 | (nil)) 771 | 772 | and :file:`test.c.237r.expand.dot`: 773 | 774 | .. image:: images/test.c.237r.expand.dot-in-xdot.png 775 | 776 | The RTL form of the IR is much closer to assembler: whereas gimple works 777 | in terms of variables of specific data types, RTL instructions work in 778 | terms of low-level operations on an arbitrary number of registers of 779 | specific bit sizes. 780 | 781 | There are about 100 RTL optimization passes, which solve problems such as: 782 | 783 | * implementing function call/return, parameter passing, and the stack of 784 | frames, in terms of what actually exists at the CPU level (the 785 | "calling conventions" of an ABI) 786 | 787 | * using the registers actually available on the CPU, rather than 788 | blithely assuming that there's an arbitrary number of registers for 789 | every function, a process called register allocation 790 | 791 | * using the instructions and addressing modes actually available 792 | on the CPU, rather than assuming an ideal set of combinations 793 | 794 | * various optimizations, such as scheduling instructions so that they 795 | run efficiently on the target CPU (e.g. handling delay slots) 796 | 797 | * converting the CFG that RTL inherited from gimple into a flat series of 798 | instructions connected by jumps (honoring constraints such as 799 | limitations on how many bytes a jump instruction can go) 800 | 801 | The official documentation for RTL is 802 | `here `_. 803 | 804 | The "final" form of RTL 805 | *********************** 806 | 807 | Eventually the RTL form is suitable for output in assembler, in an 808 | optimization pass called "final" (which, annoyingly, is no longer the 809 | final pass); the :file:`test.c.320r.final` dump file looks like this: 810 | 811 | .. code-block:: lisp 812 | 813 | ;; Function test (test, funcdef_no=0, decl_uid=1933, cgraph_uid=1, symbol_order=0) 814 | 815 | 816 | 817 | test 818 | 819 | Dataflow summary: 820 | ;; fully invalidated by EH 0 [ax] 1 [dx] 2 [cx] 4 [si] 5 [di] 8 [st] 9 [st(1)] 10 [st(2)] 11 [st(3)] 12 [st(4)] 13 [st(5)] 14 [st(6)] 15 [st(7)] 17 [flags] 18 [fpsr] 20 [xmm0] 21 [xmm1] 22 [xmm2] 23 [xmm3] 24 [xmm4] 25 [xmm5] 26 [xmm6] 27 [xmm7] 28 [mm0] 29 [mm1] 30 [mm2] 31 [mm3] 32 [mm4] 33 [mm5] 34 [mm6] 35 [mm7] 36 [r8] 37 [r9] 38 [r10] 39 [r11] 44 [xmm8] 45 [xmm9] 46 [xmm10] 47 [xmm11] 48 [xmm12] 49 [xmm13] 50 [xmm14] 51 [xmm15] 52 [xmm16] 53 [xmm17] 54 [xmm18] 55 [xmm19] 56 [xmm20] 57 [xmm21] 58 [xmm22] 59 [xmm23] 60 [xmm24] 61 [xmm25] 62 [xmm26] 63 [xmm27] 64 [xmm28] 65 [xmm29] 66 [xmm30] 67 [xmm31] 68 [k0] 69 [k1] 70 [k2] 71 [k3] 72 [k4] 73 [k5] 74 [k6] 75 [k7] 821 | ;; hardware regs used 7 [sp] 822 | ;; regular block artificial uses 7 [sp] 823 | ;; eh block artificial uses 7 [sp] 16 [argp] 824 | ;; entry block defs 0 [ax] 1 [dx] 2 [cx] 4 [si] 5 [di] 7 [sp] 20 [xmm0] 21 [xmm1] 22 [xmm2] 23 [xmm3] 24 [xmm4] 25 [xmm5] 26 [xmm6] 27 [xmm7] 36 [r8] 37 [r9] 825 | ;; exit block uses 0 [ax] 7 [sp] 826 | ;; regs ever live 0 [ax] 1 [dx] 2 [cx] 4 [si] 5 [di] 17 [flags] 827 | ;; ref usage r0={4d,5u} r1={2d,3u} r2={1d,1u} r4={2d,3u} r5={1d,1u} r7={1d,4u} r17={5d,1u} r20={1d} r21={1d} r22={1d} r23={1d} r24={1d} r25={1d} r26={1d} r27={1d} r36={1d} r37={1d} 828 | ;; total ref usage 44{26d,18u,0e} in 11{11 regular + 0 call} insns. 829 | (note 1 0 7 NOTE_INSN_DELETED) 830 | (note 7 1 48 2 [bb 2] NOTE_INSN_BASIC_BLOCK) 831 | (note 48 7 2 2 NOTE_INSN_PROLOGUE_END) 832 | (note 2 48 6 2 NOTE_INSN_DELETED) 833 | (note 6 2 5 2 NOTE_INSN_FUNCTION_BEG) 834 | (insn:TI 5 6 9 2 (set (reg/v:SI 0 ax [orig:88 d ] [88]) 835 | (reg:SI 2 cx [97])) "test.c":2:1 67 {*movsi_internal} 836 | (expr_list:REG_DEAD (reg:SI 2 cx [97]) 837 | (nil))) 838 | (insn 9 5 10 2 (set (reg:CCZ 17 flags) 839 | (compare:CCZ (reg:SI 5 di [94]) 840 | (const_int 0 [0]))) "test.c":3:6 7 {*cmpsi_ccno_1} 841 | (expr_list:REG_DEAD (reg:SI 5 di [94]) 842 | (nil))) 843 | (jump_insn 10 9 11 2 (set (pc) 844 | (if_then_else (eq (reg:CCZ 17 flags) 845 | (const_int 0 [0])) 846 | (label_ref 16) 847 | (pc))) "test.c":3:6 736 {*jcc} 848 | (expr_list:REG_DEAD (reg:CCZ 17 flags) 849 | (int_list:REG_BR_PROB 536870916 (nil))) 850 | -> 16) 851 | (note 11 10 12 3 [bb 3] NOTE_INSN_BASIC_BLOCK) 852 | (insn:TI 12 11 13 3 (parallel [ 853 | (set (reg:SI 4 si [89]) 854 | (minus:SI (reg/v:SI 4 si [orig:86 b ] [86]) 855 | (reg/v:SI 1 dx [orig:87 c ] [87]))) 856 | (clobber (reg:CC 17 flags)) 857 | ]) "test.c":4:15 254 {*subsi_1} 858 | (expr_list:REG_DEAD (reg/v:SI 1 dx [orig:87 c ] [87]) 859 | (expr_list:REG_UNUSED (reg:CC 17 flags) 860 | (nil)))) 861 | (insn:TI 13 12 52 3 (parallel [ 862 | (set (reg:SI 0 ax [orig:84 ] [84]) 863 | (mult:SI (reg/v:SI 0 ax [orig:88 d ] [88]) 864 | (reg:SI 4 si [89]))) 865 | (clobber (reg:CC 17 flags)) 866 | ]) "test.c":4:20 378 {*mulsi3_1} 867 | (expr_list:REG_DEAD (reg:SI 4 si [89]) 868 | (expr_list:REG_UNUSED (reg:CC 17 flags) 869 | (nil)))) 870 | (insn 52 13 45 3 (use (reg/i:SI 0 ax)) -1 871 | (nil)) 872 | (jump_insn:TI 45 52 46 3 (simple_return) "test.c":4:20 767 {simple_return_internal} 873 | (nil) 874 | -> simple_return) 875 | (barrier 46 45 16) 876 | (code_label 16 46 17 4 2 (nil) [1 uses]) 877 | (note 17 16 18 4 [bb 4] NOTE_INSN_BASIC_BLOCK) 878 | (insn:TI 18 17 19 4 (parallel [ 879 | (set (reg:SI 1 dx [90]) 880 | (minus:SI (reg/v:SI 1 dx [orig:87 c ] [87]) 881 | (reg/v:SI 4 si [orig:86 b ] [86]))) 882 | (clobber (reg:CC 17 flags)) 883 | ]) "test.c":6:15 254 {*subsi_1} 884 | (expr_list:REG_DEAD (reg/v:SI 4 si [orig:86 b ] [86]) 885 | (expr_list:REG_UNUSED (reg:CC 17 flags) 886 | (nil)))) 887 | (insn:TI 19 18 26 4 (parallel [ 888 | (set (reg:SI 0 ax [orig:84 ] [84]) 889 | (mult:SI (reg/v:SI 0 ax [orig:88 d ] [88]) 890 | (reg:SI 1 dx [90]))) 891 | (clobber (reg:CC 17 flags)) 892 | ]) "test.c":6:20 378 {*mulsi3_1} 893 | (expr_list:REG_DEAD (reg:SI 1 dx [90]) 894 | (expr_list:REG_UNUSED (reg:CC 17 flags) 895 | (nil)))) 896 | (insn 26 19 55 4 (use (reg/i:SI 0 ax)) "test.c":7:1 -1 897 | (nil)) 898 | (note 55 26 50 4 NOTE_INSN_EPILOGUE_BEG) 899 | (jump_insn:TI 50 55 51 4 (simple_return) "test.c":7:1 767 {simple_return_internal} 900 | (nil) 901 | -> simple_return) 902 | (barrier 51 50 47) 903 | (note 47 51 0 NOTE_INSN_DELETED) 904 | 905 | There isn't a corresponding :file:`.dot` dump file, as by this point 906 | the CFG has been flattened away into a stream of instructions. 907 | 908 | There's a fairly direct correspondence between the above and the 909 | generated assembler file, although you have to know a bit about RTL to 910 | see it. For example if we just look at the ``insn`` instructions, we 911 | can see that e.g. the final multiply instruction above: 912 | 913 | .. code-block:: lisp 914 | 915 | (insn:TI 19 18 26 4 (parallel [ 916 | (set (reg:SI 0 ax [orig:84 ] [84]) 917 | (mult:SI (reg/v:SI 0 ax [orig:88 d ] [88]) 918 | (reg:SI 1 dx [90]))) 919 | (clobber (reg:CC 17 flags)) 920 | ]) "test.c":6:20 378 {*mulsi3_1} 921 | (expr_list:REG_DEAD (reg:SI 1 dx [90]) 922 | (expr_list:REG_UNUSED (reg:CC 17 flags) 923 | (nil)))) 924 | 925 | i.e. "set %eax to the result of multipying %eax and %edx, 926 | clobbering the CC register" becomes: 927 | 928 | .. code-block:: asm 929 | 930 | imull %edx, %eax # tmp90, 931 | 932 | in the output :file:`test.s` assembler file. 933 | --------------------------------------------------------------------------------