diff --git a/README.md b/README.md index 49cc88ba1..722d8c616 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,9 @@ Swift, Pascal, [ispc](https://ispc.github.io/), Python, Java, or any of the othe time. Multiple compilers are supported for each language, many different tools and visualizations are available, and the UI layout is configurable (thanks to [GoldenLayout](https://www.golden-layout.com/)). -Try out at [godbolt.org](https://godbolt.org), or [run your own local instance](#running-a-local-instance). +Try out at [godbolt.org](https://godbolt.org), or [run your own local instance](#running-a-local-instance). An overview +of what the site lets you achieve, why it's useful, and how to use it is +[available here](docs/WhatIsCompilerExplorer.md). **Compiler Explorer** follows a [Code of Conduct](CODE_OF_CONDUCT.md) which aims to foster an open and welcoming environment. diff --git a/docs/WhatIsCompilerExplorer.md b/docs/WhatIsCompilerExplorer.md new file mode 100644 index 000000000..a1151b481 --- /dev/null +++ b/docs/WhatIsCompilerExplorer.md @@ -0,0 +1,171 @@ +# What is Compiler Explorer? + +This document is a general overview of the why, what and how of Compiler Explorer. The site lets you see how a compiler +sees your code. In its default view it will show you the assembly output of your compiler. If you are only interested in +running a program and seeing its output, skip to the section on "Execution" below. + +## Interacting with the assembly output of a compiler + +If you're familiar with compilers you may wish to skip the background. Else, read on! + +### Background + +Many programming languages are _compiled_, which means their program source text has to be converted into something a +computer can run. Ultimately, computers can only run _machine code_: a series of numbers representing the steps the +machine has to perform. Compilers are programs which take the source of a program and convert it into the machine code +the computer will run. The machine code is very specific to the kind of CPU in the computer. + +For example a machine code program to add two numbers together, with 32-bit inputs specified in CPU _registers_ `edi` +and `esi`, and result left in `eax`: + +``` +01fe89f0c3 +``` + +Machine code may be what the computer needs, but as you can see it is not a convenient representation for humans. +Instead, a simple encoding of machine code is called _assembly_ is commonly used. The encoding is bidirectional: humans +can write assembly and have it encoded as machine code with a program called an _assembler_, and machine code can be +turned into assembly with a _disassembler_. + +The same code as above in machine code is (arguably!) a little easier to comprehend: + +```nasm +add esi, edi ; corresponds to the bytes 01 fe +mov eax, esi ; corresponds to the bytes 89 f0 +ret ; corresponds to the byte c3 +``` + +Assembly is easier to understand but is still a lot lower-level and complex than most programmers want to deal with, +full of very CPU-specific information. In a higher level language like C you would probably have written this code as: + +```c +int add(int x, int y) { + return x + y; +} +``` + +To turn this into the machine code, you would run this source through a C compiler (for example, GCC). The compiler not +only parses and understands the C language, turning the programmer's intention into the nitty-gritties of the target +CPU's machine code, it can also perform _optimizations_ which can significantly improve the code performance over a +naive transliteration. + +For example, passing GCC the C source above and asking it to optimize produces the following machine code/assembly: + +```nasm +lea eax,[rdi+rsi*1] ; corresponds to machine code bytes 8d 04 37 +ret ; corresponds to machine code byte c3 +``` + +In this case GCC has been able to use a different machine code instruction (`lea`) to perform the add of `edi` and `esi` +_and_ put the result directly into the `eax` register. This has saved one byte of program space as well as one +instruction of execution. + +### Compiler Explorer + +So, what is Compiler Explorer, and how does it fit into this? As programming languages get more complex, and compilers +and their optimizers become more sophisticated, it can be useful to understand what actual machine code is generated. +Compiler Explorer lets you explore the capabilities of your language, compiler and optimizer in an interactive way. + +The default view of Compiler Explorer shows an editor window on the left, with a very simple demonstrative example +program, and the assembly output of the compiler on the right. By default, Compiler Explorer will show a C++ program, +but you can pick the language from the language selection drop-down at the top right of the editor. + +![Explanatory](images/CE-explain.svg) + +The compilation output appears immediately, and will update as you edit the code. Each line is highlighted with a +different colour, and as best as we can track it the resulting assembly code corresponding to that line of source code +is highlighted with the same colour. Mousing over a line in either the source or the assembly will briefly highlight the +corresponding line in the other window too. Hovering over an assembly opcode will give an overview of what that +instruction does, and more information is available by right-clicking and selecting "View assembly documentation". + +By default, the compiler is run with no optimization enabled, so the output is often long. Compilers will generate very +verbose, naive code without any optimization. To enable optimization, and change other aspects of the compilation, you +will need to change the command-line arguments passed to the compiler. To do so, add the flags in the input box at the +top right of the compiler output window. If you are using C++, commonly the optimizer can be enabled with `-O` followed +by an optimization level (0-3), so `-O1` is minimal optimization, and `-O3` is aggressive optimization. + +Compiler Explorer supports many different compilers. The drop-down on the top left of the compiler window lets you +select a different compiler. You can favourite the compilers you use the most by clicking the yellow star, and you can +pop out a whole compiler selection dialog by choosing either the "Pop out" button or clicking the icon at the right of +the selection panel. + +Sometimes you'll need to see the compiler's diagnostic messages (though Compiler Explorer tries to parse and highlight +relevant parts of the output in the editor window). To view the compiler's output you can bring up the output pane by +clicking or dragging the "Output" button at the bottom of the compiler window. Note that all the panes within the site +can be resized, rearranged and stacked by dragging the relevant parts of the UI. + +There are many options in the compiler's output that can be changed by changing the options available on the various +drop-downs on the compiler view, including the intelligent filtering Compiler Explorer applies to the compiler's output, +and also changing whether we try and link and execute the resulting code. + +## Execution + +Compiler Explorer allows you to edit your code and see what it outputs, once compiled. There are two ways to do this: + +1. using the default "assembly" view, and then ticking the "Execute the code" option in the compiler options. This will + then show the assembly output, and the program output will be displayed in the output window (where the compiler + errors etc would be shown). +2. using an "Execute only" view. This doesn't show any assembly and lets you just see the output of your program. This + also has the benefit of letting you pass command-line arguments and standard input to your program + +### Using the assembly view + +To use the first approach, click the "Options" dropdown on the assembly window, then tick the "Execute the code": + +![Execute the code](images/Execute.png) + +The program status and output will appear in the compiler output window, which can be opened by clicking or dragging the +"Output" button at the bottom of the assembly view: + +![Code, executed](images/Executed.png) + +### Using an "Execute only" view + +Compiler Explorer supports a view that only executes the code you're editing. There are two ways to create such a view: + +#### From the source code view + +Click "Add new..." on the source code view and click or drag "Execution Only". + +![Execute only](images/AddExecuteOnly.png) + +#### From the assembly view + +Click "Add new..." on the assembly view and click or drag "Executor From This". + +![Executor from this](images/ExecutorFromThis.png) + +This approach will clone all the compiler settings and options from the compiled assembly view. + +On boths cases, once created, the Execute Only view can be used to pick and choose compilers and compiler arguments just +like the assembly view; but additionally you can add command-line options and standard input to your program. Each +assembly or execution view is separate from the others; you can close the assembly view if you're not interested in its +output. + +## General UI + +You can click and drag each pane around to rearrange and resize it. You can also maximise a pane to make it take up the +whole page, or close it, with the two buttons at the top right. + +Assembly views support extra child panes, and support tooling. + +Child panes can be created with the "Add new..." button and include views that are compiler-specific. For example, for +`clang`-based compilers we can supply additional command-line options to the compiler to emit optimization information, +and then display it with the "LLVM Opt Pipeline" pane. There are similar panes for the `gcc`-based compilers. Some +panes, like the "Control Flow Graph" work on most compilers. + +Tool windows include separate binary tools that run over the result of compilation, independent of the compiler. For +example, we can run the UNIX command `strings` over the compilation result to show all the strings in the binary. To add +a tool, use the "Add tool..." button on the assembly view. + +Compiler Explorer supports integrating with some sister sites: CPP Insights, and Quick-Bench. We also emit a number of +other metrics about the compilation, accessible from the bottom of the assembly window: + +![Some other stuff](images/brief_overview.png) + +## More information + +This introduction covers only a few of Compiler Explorer's features. For more information please join our +[welcoming Discord](https://discord.gg/B5WacA7) and feel free to ask questions there. There is also a +[two-part video series on YouTube](https://www.youtube.com/watch?v=4_HL3PH4wDg) that shows a slightly out of date +version of the site, but might still be useful for learners. diff --git a/docs/images/AddExecuteOnly.png b/docs/images/AddExecuteOnly.png new file mode 100644 index 000000000..b9e8b1a10 Binary files /dev/null and b/docs/images/AddExecuteOnly.png differ diff --git a/docs/images/CE-explain.svg b/docs/images/CE-explain.svg new file mode 100644 index 000000000..36dc6d831 --- /dev/null +++ b/docs/images/CE-explain.svg @@ -0,0 +1,1923 @@ + + + +SelectlanguageSourcecodeAssemblycodeCompileroptionsShareSelectcompilerOpen outputwindowHighlightedbackgroundFilters &options diff --git a/docs/images/Execute.png b/docs/images/Execute.png new file mode 100644 index 000000000..0eee66aa1 Binary files /dev/null and b/docs/images/Execute.png differ diff --git a/docs/images/Executed.png b/docs/images/Executed.png new file mode 100644 index 000000000..ae450ed15 Binary files /dev/null and b/docs/images/Executed.png differ diff --git a/docs/images/ExecutorFromThis.png b/docs/images/ExecutorFromThis.png new file mode 100644 index 000000000..36a25a684 Binary files /dev/null and b/docs/images/ExecutorFromThis.png differ