mirrors/compiler-explorer
1
0
Fork 0
mirror of https://github.com/compiler-explorer/compiler-explorer.git synced 2025-12-27 09:23:52 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve docs (Wording & raw and stylized visuals)

Browse Source
This commit is contained in:
RabsRincon
2018-03-19 03:48:26 +01:00
parent 3e8b2c8122
commit ebf416a5e1
5 changed files with 224 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
AUTHORS.md Normal file
View File

@@ -0,0 +1,5 @@
[Matt Godbolt](http://xania.org)
[Rubén Rincón](https://github.com/RabsRincon)
[Jared Wyles](https://github.com/jaredwy)
[Patrick Quist](https://github.com/partouf)
[Simon Brand](https://blog.tartanllama.xyz/)

71
CODE_OF_CONDUCT.md
View File

@@ -1,46 +1,77 @@
# Contributor Covenant Code of Conduct
**Compiler Explorer** contributor covenant Code of Conduct.
## Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project
and our community a harassment-free experience for everyone, regardless of age,
body size, disability, ethnicity, gender identity and expression,
level of experience, nationality, personal appearance, race, religion,
or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
* Using welcoming and inclusive language.
* Being respectful of differing viewpoints and experiences.
* Gracefully accepting constructive criticism.
* Focusing on what is best for the community.
* Showing empathy towards other community members.
Examples of unacceptable behavior by participants include:
Examples of **unacceptable** behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
* The use of sexualized language or imagery and unwelcome sexual attention or
advances.
* Trolling, insulting/derogatory comments, and personal or political attacks.
* Public or private harassment.
* Publishing others' private information, such as a physical or electronic
address, without explicit permission.
* Other conduct which could reasonably be considered inappropriate in a
professional setting.
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban
temporarily or permanently any contributor for other behaviors that they deem
inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as
an appointed representative at an online or offline event.
Representation of a project may be further defined and clarified by project
maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project owner at matt@godbolt.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project owner at
[matt@godbolt.org](mailto:matt@godbolt.org). The project team will review
and investigate all complaints, and will respond in a way that it deems
appropriate to the circumstances. The project team is obligated to maintain
confidentiality with regard to the reporter of an incident. Further details of
specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 1.4, available at [contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
[homepage]: https://www.contributor-covenant.org/
[version]: https://www.contributor-covenant.org/version/1/4/

102
CONTRIBUTING.md
View File

@@ -1,51 +1,85 @@
# Contributing to Compiler Explorer
First of, if you're reading this: thank you! Even considering contributing to Compiler Explorer is very much appreciated!
Before we go too far, an apology: Compiler Explorer grew out of a bit of hacky JavaScript into a pretty large and
well-used project pretty quickly. Not all the code was originally well-written or well-tested. Please be forgiving of that,
and be ready to help in improving that.
First of, if you're reading this: thank you! Even considering contributing to
**Compiler Explorer** is very much appreciated!
Before we go too far, an apology: **Compiler Explorer** grew out of a bit of
hacky JavaScript into a pretty large and well-used project pretty quickly.
Not all the code was originally well-written or well-tested.
Please be forgiving of that, and be ready to help in improving that.
Note that Compiler Explorer targets the latest Node.js LTS, so it's better if you do so as well when testing your changes locally.
(But it *should* run in everything post-Node.js 8)
**Compiler Explorer** follows a [Code of Conduct](CODE_OF_CONDUCT.md) which
aims to foster an open and welcoming environment.
## Node version
**Compiler Explorer** targets the latest [Node.js](https://nodejs.org/) LTS,
so it's better if you do so as well when testing your changes locally.
Nonetheless, it _should_ run in everything post-Node.js 8. [Contact us]
## In brief
* Make your changes, trying to stick to the style and code format where possible. We use default IntelliJ settings,
if that helps.
* If adding a new server-side component please do your best to add a test to cover it. For client-side changes that's trickier,
but do your best to help us improve this situation.
* Run the git hooks installer (Only needed once): `make install-git-hooks`. This will automatically run the tests before
every commit, ensuring that they pass before commiting your changes. _You can disable this check with `git commit --no-verify` if needed_.
* Do a smoke test: run `make` and ensure the site works as you'd expect. Concentrate on the areas you'd expect to have
changed, but if you can, click about generally to help check you haven't unintentionally broken something else.
* Submit a PR.
* If you have any questions, don't hesitate to email matt@godbolt.org or join the cpplang slack channel and talk on
 channel #compiler_explorer
* Make your changes, trying to stick to the style and format where possible.
* We use [ESLint](https://eslint.org/) to ensure a consistent code base
and PRs won't pass unless it detects no errors.
* Running `make lint` will run the linter, which will auto-fix everything
it can and report back any errors and warnings.
* If adding a new server-side component please do your best to add a test to
cover it. For client-side changes that's trickier.
* Run the git hooks installer (_Only needed once_): `make install-git-hooks`.
This will automatically run the tests before you can commit, ensuring that
they pass before committing your changes.
_You can disable this check with `git commit --no-verify` if needed_.
* You can run `make check` to run both the linter and the code tests
* Do a smoke test:
Run `make` and ensure the site works as you'd expect. Concentrate on the
areas you'd expect to have changed, but if you can, click about generally to
help check you haven't unintentionally broken something else
* Submit a Pull Request.
If you have any questions, don't hesitate: [Contact us].
## Basic code layout
Code is separated into server-side code and client-side code. All dependencies (server and client side) are installed via `package.json`.
Server code is in `app.js` and in the `lib` directory. Client code is all in the `static` directory.
Code is separated into server-side code and client-side code.
All dependencies (server and client side) are installed via `package.json`.
_Server code_ is in `app.js` and in the `lib` directory.
_Client code_ is all in the `static` directory.
In the server code, the `app.js` sets up a basic `express` middleware-driven web server, delegating to the various compiler
backends in `lib/compilers`. All of them inherit from `lib/base-compiler.js` which does most of the work of running
compilers, then parsing the output and forming a JSON object to send to the client. Any assembly parsing is done in `asm.js`.
In the server code, the `app.js` sets up a basic `express`
middleware-driven web server, delegating to the various compiler backends in
`lib/compilers/`. All of them inherit from `lib/base-compiler.js` which does
most of the work of running compilers, then parsing the output and forming a
JSON object to send to the client. Any assembly parsing is done in the
`lib/asm.js`, and similar, files.
In the client code, GoldenLayout is used as the container. If you look at some of the components like the `static/compiler.js`,
you'll see the general flow. Any state stored makes it into the URL, so be careful not to stash anything too big in there.
In the client code, [GoldenLayout](https://www.golden-layout.com/) is used as
the container. If you look at some of the components like the
`static/compiler.js`, you'll see the general flow.
Any state stored makes it into the URL, so be careful not to stash
anything too big in there.
The client code follows GoldenLayout's message-based system: no component has a reference to any other and everything is done
via messages. This will (in future) allow us to use pop-out windows, if we ever need to (as the messages are JSON-serialisable
between separate windows).
The client code follows GoldenLayout's message-based system:
no component has a reference to any other and everything is done via messages.
This will allow us to use pop-out windows, if we ever need to, as the messages
are JSON-serializable between separate windows.
## Editing flow
The recommended way to work on Compiler Explorer is to just run `make` and let the automatic reload stuff do its magic.
Any changes to the server code will cause the server to reload, and any changes to the client code will be reflected upon
a page reload. This makes for a pretty quick turnaround.
The recommended way to work on **Compiler Explorer** is to just run `make dev`
and let the automatic reloading do its magic.
Any changes to the server code will cause the server to reload, and any changes
to the client code will be reflected upon a page reload.
This makes for a pretty quick turnaround.
Note that a current issue makes every project media asset to be locally
unavailable. We will hopefully fix this in the near future.
## Gotchas
* Don't use new-style JS (`let` or arrow operators) in the client-side code. Sadly there's still enough users out there
 on old browsers. But feel free to use all the cool stuff on the server side code.
* Be aware Compiler Explorer runs on a cluster on the live site. No local state is kept between invocations, and it's likely
the user's next request will hit another node in the cluster, so don't rely on any in-memory state.
* Stick to **ES5** (no `let` or arrow operators) in the client-side code.
Sadly there are still enough users out there on old browsers,
but feel free to use all the cool stuff on the server side code.
* Be aware that **Compiler Explorer** runs on a cluster on the live site.
No local state is kept between invocations, and the user's next request will
likely hit a different node in the cluster, so don't rely on
any in-memory state.
[Contact us]: README.md#contact-us

143
README.md
View File

@@ -6,76 +6,107 @@
Compiler Explorer
------------
Compiler Explorer is an interactive compiler. The left-hand pane shows editable C, C++, Rust, Go, D, Haskell, Swift and Pascal code.
The right, the assembly output of having compiled the code with a given compiler and settings. Multiple compilers are supported, and
the UI layout is configurable (the [Golden Layout](https://www.golden-layout.com/) library is used for this).
There is also an ispc compiler for a C variant with extensions for SPMD.
**Compiler Explorer** is an interactive compiler. The left-hand pane shows
editable C, C++, Rust, Go, D, Haskell, Swift and Pascal code.
The right, the assembly output of having compiled the code with a given
compiler and settings. Multiple compilers are supported, and the UI layout
is configurable (thanks to [GoldenLayout](https://www.golden-layout.com/)).
There is also an ispc compiler _[?](https://ispc.github.io/)_ for a C variant
with extensions for SPMD.
Try out at [godbolt.org](https://godbolt.org)
You can support [this project on Patreon](https://patreon.com/mattgodbolt).
**Compiler Explorer** follows a [Code of Conduct](CODE_OF_CONDUCT.md) which
aims to foster an open and welcoming environment.
##### Contact us
For general discussion, feel free to join the mailing list: https://groups.google.com/forum/#!forum/compiler-explorer-discussion or the cpplang slack https://cpplang.now.sh/ channel `#compiler_explorer`.
For general discussion, feel free to join the mailing list at
https://groups.google.com/forum/#!forum/compiler-explorer-discussion or the
[cpplang](https://cpplang.now.sh/) slack channel `#compiler_explorer`.
If you are interested in developing, or want to see the discussions between existing developers, feel free to join the mailing list at https://groups.google.com/forum/#!forum/compiler-explorer-development or the cpplang slack https://cpplang.now.sh/ channel `#ce_implementation`.
If you are interested in developing, or want to see the discussions between
existing developers, feel free to join the mailing list at
https://groups.google.com/forum/#!forum/compiler-explorer-development or the
[cpplang](https://cpplang.now.sh/) slack channel `#ce_implementation`.
Feel free to raise an issue on
[github](https://github.com/mattgodbolt/compiler-explorer/issues) or
[email Matt directly](mailto:matt@godbolt.org) for more help.
### Developing or running a local instance
Compiler Explorer is written in node.js.
**Compiler Explorer** is written in [Node.js](https://nodejs.org/).
Assuming you have a compatible version of `node` installed, simply running `make` ought to get you up and running with an Explorer
running on port 10240 on your local machine: http://localhost:10240/. Currently Compiler Explorer requires `node` v8 installed, either on the path or at `NODE_PATH` (an environment variable or `make` parameter).
Assuming you have a compatible version of `node` installed, simply running
`make` ought to get you up and running with an Explorer running on port 10240
on your local machine: http://localhost:10240/.
Currently **Compiler Explorer**
[requires the latest LTS](CONTRIBUTING.md#node-version) `node` version
(_v8_) installed, either on the path or at `NODE_PATH`
(an environment variable or `make` parameter).
Running with `make EXTRA_ARGS='--language LANG'` will allow you to load `LANG` exclusively, where `LANG` is one for the language ids/aliases defined in `lib/languages.js`
The `Makefile` will automatically install all the third party libraries needed to run; using `yarn` to install server-side and client side components
Running with `make EXTRA_ARGS='--language LANG'` will allow you to load
`LANG` exclusively, where `LANG` is one for the language ids/aliases defined
in `lib/languages.js`. The `Makefile` will automatically install all the
third party libraries needed to run; using `yarn` to install server-side and
client side components.
If you want to point it at your own GCC or similar binaries, either edit the `etc/config/compiler-explorer.defaults.properties` or else make a new one with the name
`compiler-explorer.local.properties`. `*.local.properties` files have the highest priority when loading properties.
If you want to point it at your own GCC or similar binaries, either edit the
`etc/config/compiler-explorer.defaults.properties` or else make a new one with
the name `compiler-explorer.local.properties`. `*.local.properties` files
have the highest priority when loading properties.
The config system leaves a lot to be desired, I'm working on porting [CCS](https://github.com/hellige/ccs-cpp) to javascript and then something more rational can be used.
The config system leaves a lot to be desired. Work has been done on porting
[CCS](https://github.com/hellige/ccs-cpp) to Javascript and then something
more rational can be used.
Feel free to raise an issue on [github](https://github.com/mattgodbolt/compiler-explorer/issues) or
[email me directly](mailto:matt@godbolt.org) for more help.
There's now a [Road map](Roadmap.md) that gives a little insight into future plans for Compiler Explorer.
A [Road map](Roadmap.md) is available which gives a little insight into
the future plans for **Compiler Explorer**.
### RESTful API
There's a simple restful API that can be used to do compiles to asm and to list compilers. In general
all handlers live in `/api/*` endpoints, and will accept JSON or text in POSTs, and will return text responses
or JSON responses depending on the request's `Accept` header.
There's a simple restful API that can be used to do compiles to asm and to
list compilers. In general all handlers live in `/api/*` endpoints, will
accept JSON or text in POSTs, and will return text or JSON responses depending
on the request's `Accept` header.
At a later date there may be some form of rate-limiting: currently requests will be queued and dealt with
exactly like interactive requests on the main site. Authentication might be required at some point in the
future (for the main Compiler Explorer site anyway).
At a later date there may be some form of rate-limiting:
currently, requests will be queued and dealt with in the same way interactive
requests are done for the main site. Authentication might be required at some
point in the future (for the main **Compiler Explorer** site anyway).
The following endpoints are defined:
#### `GET /api/languages` - return a list of languages
Returns a list of the currently supported languages, as pairs of languages IDs and their names.
Returns a list of the currently supported languages, as pairs of languages IDs
and their names.
#### `GET /api/compilers` - return a list of compilers
Returns a list of compilers. In text form, there's a simple formatting of the ID of the compiler, its
description and its language ID. In JSON, all the information is returned as an array of compilers, with the `id` key being the
primary identifier of each compiler.
Returns a list of compilers. In text form, there's a simple formatting of the
ID of the compiler, its description and its language ID. In JSON, all the
information is returned as an array of compilers, with the `id` key being the
primary identifier of each compiler.
#### `GET /api/compilers/<language-id>` - return a list of compilers with matching language
Returns a list of compilers for the provided language id. In text form, there's a simple formatting of the ID of the compiler, its
description and its language ID. In JSON, all the information is returned as an array of compilers, with the `id` key being the
primary identifier of each compiler.
Returns a list of compilers for the provided language id. In text form,
there's a simple formatting of the ID of the compiler, its description and its
language ID. In JSON, all the information is returned as an array of compilers,
with the `id` key being the primary identifier of each compiler.
#### `POST /api/compiler/<compiler-id>/compile` - perform a compilation
To specify a compilation request as a JSON document, post it as the appropriate type and send an object of
the form:
To specify a compilation request as a JSON document, post it as the appropriate
type and send an object of the form:
```JSON
{
"source": "Source to compile",
@@ -88,18 +119,22 @@ the form:
}
}
```
The filters are an JSON object with true/false. If not supplied, defaults are used. If supplied, the
filters are used as-is. The `compilerOptions` is used to pass extra arguments to the back end, and is probably
not useful for most REST users.
The filters are a JSON object with `true`/`false` values. If not supplied,
defaults are used. If supplied, the filters are used as-is.
The `compilerOptions` is used to pass extra arguments to the back end, and is
probably not useful for most REST users.
A text compilation request has the source as the body of the post, and uses query parameters to pass the
options and filters. Filters are supplied as a comma-separated string. Use the query parameter `filters=XX`
to set the filters directly, else `addFilters=XX` to add a filter to defaults, or `removeFilters` to remove from defaults. Compiler parameters should be passed as `options=-O2` and default to empty.
A text compilation request has the source as the body of the post, and uses
query parameters to pass the options and filters. Filters are supplied as a
comma-separated string. Use the query parameter `filters=XX` to set the
filters directly, else `addFilters=XX` to add a filter to defaults,
or `removeFilters` to remove from defaults.
Compiler parameters should be passed as `options=-O2` and default to empty.
Filters include `binary`, `labels`, `intel`, `comments` and `directives` and correspond to the UI buttons on
the HTML version.
Filters include `binary`, `labels`, `intel`, `comments`, `directives` and
`demangle`, which correspond to the UI buttons on the HTML version.
The text request is designed for simplicity for command-line clients like `curl`:
The text request is designed for simplicity for command-line clients like `curl`
```bash
$ curl 'https://godbolt.org/api/compiler/g63/compile?options=-Wall' --data-binary 'int foo() { return 1; }'
@@ -112,9 +147,10 @@ foo():
ret
```
If JSON is present in the request's `Accept` header, the compilation results are of the form:
If JSON is present in the request's `Accept` header, the compilation results
are of the form:
Optional values are marked with a '**'
(_Optional values are marked with a `**`_)
```javascript
{
@@ -155,12 +191,15 @@ Optional values are marked with a '**'
### Credits
Compiler Explorer is maintained by [Matt Godbolt](http://xania.org), [Rubén Rincón](https://github.com/RabsRincon) and [Simon Brand](https://blog.tartanllama.xyz/).
- [Gabriel Devillers](https://github.com/voxelf) - Initial multiple compilers and difference view (while working for [Kalray](http://www.kalrayinc.com/)).
- [Jared Wyles](https://github.com/jaredwy) - Clang OPT Output view and maintenance
- [Johan Engelen](https://github.com/JohanEngelen) - D support and its maintenance
- [Chedy Najjar](https://github.com/CppChedy) - CFG View and maintenance
- [Patrick Quist](https://github.com/partouf) - Pascal support, bug-fixes, windows support
- [Joshua Sheard](https://github.com/jsheard) - ISPC support
- [Marc Poulhiès](https://github.com/dkm) - GCC Dumps view
- [Andrew Pardoe](https://github.com/AndrewPardoe) - WSL-CL support
**Compiler Explorer** is maintained by the awesome people listed in the
[AUTHORS](AUTHORS.md) file.
We would also like to specially thank these people for their contributions to
**Compiler Explorer**:
- [Gabriel Devillers](https://github.com/voxelf)
(_while working for [Kalray](http://www.kalrayinc.com/)_)
- [Johan Engelen](https://github.com/JohanEngelen)
- [Chedy Najjar](https://github.com/CppChedy)
- [Joshua Sheard](https://github.com/jsheard)
- [Marc Poulhiès](https://github.com/dkm)
- [Andrew Pardoe](https://github.com/AndrewPardoe)

18
rust/Cargo.lock generated
View File

@@ -1,12 +1,3 @@
[root]
name = "rustfilt"
version = "0.1.1"
dependencies = [
"lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
"regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
"rustc-demangle 0.1.4 (registry+https://github.com/rust-lang/crates.io-index)",
]
[[package]]
name = "aho-corasick"
version = "0.6.3"
@@ -56,6 +47,15 @@ name = "rustc-demangle"
version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
[[package]]
name = "rustfilt"
version = "0.1.1"
dependencies = [
"lazy_static 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)",
"regex 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
"rustc-demangle 0.1.4 (registry+https://github.com/rust-lang/crates.io-index)",
]
[[package]]
name = "simd"
version = "0.1.1"