[GR-15251] Fixes for docs.

PullRequest: truffleruby/816

Author: chrisseaton

CONTRIBUTING.md

@@ -1,5 +1,9 @@
 Thank you for thinking about contributing something to TruffleRuby!
 
+You can build TruffleRuby from source - see the [building
+instructions](doc/contributor/workflow.md). You can also use
+[Docker](doc/contributor/docker.md) to get an automated build.
+
 You will need to sign the Oracle Contributor Agreement for us to able to merge
 your work.
 

README.md

@@ -33,10 +33,6 @@ There are three ways to install TruffleRuby:
 
 You can use `gem` to install Gems as normal.
 
-You can also build TruffleRuby from source, see the
-[building instructions](doc/contributor/workflow.md), and using
-[Docker](doc/contributor/docker.md).
-
 Please report any issue you might find on [GitHub](https://github.com/oracle/truffleruby/issues).
 
 ## Aim
@@ -58,18 +54,18 @@ important to understand the different configurations of TruffleRuby, as each has
 different capabilities and performance characteristics. You should pick the
 execution mode that is appropriate for your application.
 
-TruffleRuby by default runs in the *native*
-configuration. In this configuration, TruffleRuby is ahead-of-time compiled to a
-standalone native executable. This means that you don't need a JVM installed on
-your system to use it. The advantage of the native configuration is that it
-[starts about as fast as MRI](doc/contributor/native-image.md), it may use less memory,
-and it becomes fast in less time. The disadvantage of the native configuration
-is that you can't use Java tools like VisualVM, you can't use Java
-interoperability, and *peak performance may be lower than on the JVM*. The
-native configuration is used by default, but you can also request it using
-`--native`. To use polyglot programming with the *native* configuration, you
-need to use the `--polyglot` flag. To check you are using the *native*
-configuration, `ruby --version` should mention `Native`.
+TruffleRuby by default runs in the *native* configuration. In this
+configuration, TruffleRuby is ahead-of-time compiled to a standalone native
+executable. This means that you don't need a JVM installed on your system to
+use it. The advantage of the native configuration is that it starts about as
+fast as MRI, it may use less memory, and it becomes fast in less time. The
+disadvantage of the native configuration is that you can't use Java tools like
+VisualVM, you can't use Java interoperability, and *peak performance may be
+lower than on the JVM*. The native configuration is used by default, but you
+can also request it using `--native`. To use polyglot programming with the
+*native* configuration, you need to use the `--polyglot` flag. To check you
+are using the *native* configuration, `ruby --version` should mention
+`Native`.
 
 TruffleRuby can also be used in the *JVM* configuration, where it runs as a
 normal Java application on the JVM, as any other Java application would. The
@@ -150,8 +146,11 @@ should read our [migration guide](doc/user/jruby-migration.md).
 ## Documentation
 
 Extensive documentation is available in [`doc`](doc).
-[`doc/user`](doc/user) documents how to use TruffleRuby and
-[`doc/contributor`](doc/contributor) documents how to develop TruffleRuby.
+
+See our [source code repository](https://github.com/oracle/truffleruby) and
+[contributor
+documentation](https://github.com/oracle/truffleruby/tree/master/doc/contributor)
+to contribute to TruffleRuby.
 
 ## Contact
 

bench/chunky_png/README.md

@@ -1,5 +1,4 @@
-These benchmarks are originally from
-[Bench 9000](https://github.com/jruby/bench9000).
+These benchmarks are originally from JRuby Bench 9000.
 
 We are using ChunkyPNG at revision `efd61c8d0ddcabdcf09fb44f8e8c1ba709995940`.
 We use this old revision because we know it has interesting patterns of

bench/psd.rb/README.md

@@ -1,5 +1,4 @@
-These benchmarks are originally from
-[Bench 9000](https://github.com/jruby/bench9000).
+These benchmarks are originally from JRuby Bench 9000.
 
 We are using PSD.rb at revision `e14d652ddc705e865d8b2b897d618b25d78bcc7c`.
 We use this old revision because we know it has interesting patterns of

doc/contributor/benchmarking.md

@@ -2,7 +2,7 @@
 
 ## Benchmarking with the GraalVM Compiler
 
-```
+```bash
 $ jt benchmark bench/classic/mandelbrot.rb --simple
 ```
 
@@ -13,13 +13,13 @@ for the first few iterations).
 
 You can turn off the GraalVM Compiler if you want using `--no-graal`.
 
-```
+```bash
 $ jt benchmark --no-graal bench/classic/mandelbrot.rb --simple
 ```
 
 You can benchmark an entirely different implementation using the
 `JT_BENCHMARK_RUBY` environment variable.
 
-```
+```bash
 $ JT_BENCHMARK_RUBY=ruby jt benchmark bench/classic/mandelbrot.rb --simple
 ```

doc/contributor/building-graal.md

@@ -11,13 +11,13 @@ install Graal locally.
 Our workflow tool can install Graal automatically under the directory
 `../graal/compiler` with:
 
-```
+```bash
 $ jt install graal
 ```
 
 You can then use `jt` to run TruffleRuby with Graal.
 
-```
+```bash
 $ jt ruby --graal ...
 ```
 
@@ -32,6 +32,6 @@ You can then set the `GRAAL_HOME` environment variable to the location of the
 `compiler` directory inside the `graal` repository and use `jt` to run
 TruffleRuby.
 
-```
+```bash
 $ GRAAL_HOME=.../graal/compiler jt ruby --graal ...
 ```

doc/contributor/cexts.md

@@ -5,28 +5,28 @@
 Get the gem test pack.
 
 ```bash
-jt gem-test-pack
+$ jt gem-test-pack
 ```
 
 You can then test C extension support.
 
 ```bash
-jt test cexts
+$ jt test cexts
 ```
 
 You can also runs specs:
 
 ```bash
-jt test :capi
+$ jt test :capi
 ```
 
 ### OpenSSL
 
 The `openssl` specs and tests are currently segregated and are run separately.
 
 ```bash
-jt test :openssl
-jt test mri --openssl
+$ jt test :openssl
+$ jt test mri --openssl
 ```
 
 ## Benchmarking
@@ -40,7 +40,7 @@ jt cextc bench/chunky_png/oily_png
 Then follow the instructions for benchmarking above, and then try:
 
 ```bash
-USE_CEXTS=true TRUFFLERUBYOPT=--cexts-log-load jt benchmark bench/chunky_png/chunky-color-r.rb --simple
+$ USE_CEXTS=true TRUFFLERUBYOPT=--cexts-log-load jt benchmark bench/chunky_png/chunky-color-r.rb --simple
 ```
 
 These benchmarks have Ruby fallbacks, so we should carefully check that the

doc/contributor/docker.md

@@ -12,7 +12,7 @@ For example, to build a Docker image called `truffleruby-test` to test
 installing the public GraalVM CE binary and the public Ruby installable,
 using rbenv, and running a basic test:
 
-```
+```bash
 $ jt docker build truffleruby-test --ubuntu1804 --public 1.0.0 --rbenv --basic-test
 ```
 
@@ -23,13 +23,13 @@ built to use TruffleRuby.
 Or, to print a Dockerfile to show how to install TruffleRuby from source on
 Fedora 28 using RVM:
 
-```
+```bash
 $ jt docker print --fedora28 --source --rvm
 ```
 
 Or, to run a full set of tests on a set of new release candidate tarballs:
 
-```
+```bash
 $ jt docker test --graalvm graalvm-ce.tar.gz ruby-installable.jar --test release_branch
 $ jt docker test --graalvm graalvm-ee.tar.gz ruby-installable.jar --test release_branch
 $ jt docker test --graalvm graalvm-ee.tar.gz ruby-installable.jar --rebuild-images --test release_branch
@@ -87,7 +87,7 @@ You may find that the Docker cache interacts badly with these Dockerfiles (such
 as repository URLs being cached that become unavailable). Therefore we recommend
 regularly clearing your Docker cache.
 
-```
+```bash
 $ docker system prune -a -f
 ```
 

doc/contributor/native-image.md

@@ -33,12 +33,14 @@ warm-up time for shorter running commands and benchmarks.
 $ cd graalvm
 $ otool -L jre/bin/ruby
 jre/bin/ruby:
-	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1348.28.0)
-	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1238.0.0)
-	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.8)
+  /System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1348.28.0)
+  /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1238.0.0)
+  /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.8)
+```
 
+```bash
 $ du -h jre/bin/ruby
-200M	jre/bin/ruby
+200M jre/bin/ruby
 ```
 
 The Native Image version of TruffleRuby has better startup performance and lower memory
@@ -81,7 +83,7 @@ There is no need to do so, but you can actually also compile your own copy of
 the Native Image version of TruffleRuby using a tool distributed as part of GraalVM and
 the Java version of TruffleRuby from GraalVM.
 
-```
+```bash
 $ native-image -H:Name=native-ruby --language:ruby
 ```
 
@@ -90,7 +92,7 @@ $ native-image -H:Name=native-ruby --language:ruby
 You can build a native build of TruffleRuby using the Native Image Tool from a
 source distribution using:
 
-```
+```bash
 $ jt build native
 ```
 

doc/contributor/static-analysis.md

@@ -11,7 +11,7 @@ The [Clang Static Analyzer](https://clang-analyzer.llvm.org) finds bugs in C
 code. We occasionally run this tool locally but only take its output as a
 suggestion. We use a default configuration.
 
-```
+```bash
 $ scan-build --use-analyzer `which clang` -analyze-headers clang -c --std=c99 -Ilib/cext/include src/main/c/cext/ruby.c src/main/c/truffleposix/truffleposix.c
 $ scan-view ...as instructed by scan-build...
 ```
@@ -23,7 +23,7 @@ $ scan-view ...as instructed by scan-build...
 We have a tool to check that some use of our internal annotations and the
 Truffle DSL are correct. Passing this is enforced in our CI gate.
 
-```
+```bash
 $ jt check_dsl_usage
 ```
 
@@ -32,7 +32,7 @@ $ jt check_dsl_usage
 [CheckStyle](http://checkstyle.sourceforge.net) enforces a Java style guide.
 Passing CheckStyle is enforced in our CI gate.
 
-```
+```bash
 $ mx checkstyle
 ```
 
@@ -42,7 +42,7 @@ $ mx checkstyle
 errors. We run it with the default Graal project configuration. Passing
 SpotBugs is enforced in our CI gate.
 
-```
+```bash
 $ mx spotbugs
 ```
 
@@ -54,7 +54,7 @@ $ mx spotbugs
 It's configured in `.rubocop.yml`, and can be run locally as `jt rubocop`.
 Passing Rubocop is enforced in our CI gate.
 
-```
+```bash
 $ jt rubocop
 ```
 
@@ -64,7 +64,7 @@ $ jt rubocop
 performance improvements. We occasionally run this tool locally but only take
 its output as a suggestion. We use a default configuration.
 
-```
+```bash
 $ gem install fasterer
 $ fasterer lib/truffle lib/cext src/main
 ```
@@ -78,7 +78,7 @@ suggestion. We disable a lot of the defaults in `.reek.yml`, either because
 we're implementing a set API, because we're doing something low-level or
 outside normal Ruby semantics, or for performance reasons.
 
-```
+```bash
 $ gem install reek
 $ reek lib/truffle lib/cext src/main
 ```
@@ -89,7 +89,7 @@ $ reek lib/truffle lib/cext src/main
 check that your methods do not appear near the top of this list. We
 occasionally run this tool locally but only take its output as a suggestion.
 
-```
+```bash
 $ gem install flog
 $ flog -m -t 10 lib/truffle lib/cext src/main
 ```
@@ -100,7 +100,7 @@ $ flog -m -t 10 lib/truffle lib/cext src/main
 could potentially be factored out. We occasionally run this tool locally but
 only take its output as a suggestion.
 
-```
+```bash
 $ gem install flay
 $ flay lib/truffle lib/cext src/main
 ```
@@ -112,7 +112,7 @@ vulnerabilities. It's really designed for Rails, and many of the rules are
 specific to Rails, but we do run it ocassionally anyway and take its output as
 a suggestion.
 
-```
+```bash
 $ gem install brakeman
 $ brakeman --force-scan --run-all-checks --interprocedural --no-pager --add-libs-path src --only-files lib/truffle/,lib/cext/,src/main/ruby/core/
 ```