Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: opal/opal
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 1eb59f0ab581
Choose a base ref
...
head repository: opal/opal
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 05c477ce8438
Choose a head ref
  • 2 commits
  • 1 file changed
  • 2 contributors

Commits on Jul 9, 2015

  1. Copy the full SHA
    39d8b79 View commit details
  2. Merge pull request #987 from bbatsov/compiler-directives-doc

    Apply some fixes to the compiler directives document
    elia committed Jul 9, 2015

    Unverified

    This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
    Copy the full SHA
    05c477c View commit details
Showing with 22 additions and 22 deletions.
  1. +22 −22 docs/compiler_directives.md
44 changes: 22 additions & 22 deletions docs/compiler_directives.md
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@
# Compiler Directives

The Opal compiler supports some special directives that can optimize or
enhance the output of compiled ruby code to suit the ruby environment.
enhance the output of compiled Ruby code to suit the Ruby environment.

## Require Directive

@@ -20,22 +20,22 @@ Assuming we have a file `foo.rb`:
require 'baz'

The compiler will collect these two dependencies, and then `Builder`
will attempt to discover them within the opal load path to also compile
will attempt to discover them within the Opal load path to also compile
them into the target output. If these dependencies cannot be resolved,
then a compile time error will be thrown.

#### Dynamic Requires

Opal only supports hard-coded requires. This means that any dynamically
generated require statemnts cannot be discoeverd. Opal may raise an
generated require statements cannot be discovered. Opal may raise an
error or just produce a warning if a dynamic require is used. A dynamic
require is any require that cannot be resolved using static analysis. A
common use case of dynamic requires is to include a directory of ruby
common use case of dynamic requires is to include a directory of Ruby
files. In this case, see `require_tree` below.

### `require_relative`

`require_relative` is also supported by opals compiler for ahead-of-time
`require_relative` is also supported by Opal's compiler for ahead-of-time
inclusion.

# foo.rb
@@ -46,8 +46,8 @@ This example will try to resolve `bar.rb` in the same directory.
### `autoload`

`autoload` is used to load a modules and classes within a modules
namespace. Aslong as the string argument given to `autoload` can be
resolved in Opals load paths, in the same way as `require`, then these
namespace. As long as the string argument given to `autoload` can be
resolved in Opal's load paths, in the same way as `require`, then these
referenced dependencies will also be compiled.

# foo.rb
@@ -59,7 +59,7 @@ In this example, `bar.rb` will also be required.

### `require_tree`

`require_tree` can be used as an Opal friendly alternative to globbing
`require_tree` can be used as an Opal-friendly alternative to globbing
over a directory to require a list of dependencies.

# foo.rb
@@ -70,23 +70,23 @@ directory and also compile them to the output. At runtime this method
will then loop over all modules defined, and require them if they match
that given module path.

Note: The given directory **must** be inside Opals load path, otherwise
Note: The given directory **must** be inside Opal's load path, otherwise
no files will be compiled.

### Handling non-ruby requirements
### Handling non-Ruby requirements

Opal's `require` method is also special as it allows non-ruby source
Opal's `require` method is also special as it allows non-Ruby source
files to be required and generated in the output. The obvious example of
this is requiring javascript source files. Javascript sources are
treated as first class citizens in Opal. The Opal gem also supports
this is requiring JavaScript source files. JavaScript sources are
treated as first class citizens in Opal. The Opal gem also supports
compiling `.erb` files using the same process.

## Opal Specific Code Compilation

A special case `if` and `unless` statements can hide or show blocks of
code from the Opal compiler. These check against `RUBY_ENGINE` or
`RUBY_PLATFORM`. As these are valid ruby statements against constants
that exist in all ruby runtimes, they will not affect any running code:
`RUBY_PLATFORM`. As these are valid Ruby statements against constants
that exist in all Ruby runtimes, they will not affect any running code:

if RUBY_ENGINE == 'opal'
# this code compiles
@@ -103,25 +103,25 @@ Unless statements are also supported:
Also `!=` statements work:

if RUBY_ENGINE != 'opal'
puts "do not run this code"
puts 'do not run this code'
end

These blocks of code dont run at all at runtime, but they also never
compile so will never be in the output javascript code. This is
particularly useful for using code in both mri and Opal.
These blocks of code don't run at all at runtime, but they also never
compile so will never be in the output JavaScript code. This is
particularly useful for using code in both MRI and Opal.

Some uses are:

* Avoid `require` statements being picked up by Opal compile time
require handling.

* To stop certain requires taking place for opal (and vice-versa for
* To stop certain requires taking place for Opal (and vice-versa for
shared libraries).

* To wrap x-strings which might break in compiled javascript output.
* To wrap x-strings which might break in compiled JavaScript output.

* To simply avoid compiling large blocks of code that are not needed
in the javascript/opal version of an app.
in the JavaScript/Opal version of an app.

In all these examples `RUBY_PLATFORM` can be used instead of
`RUBY_ENGINE`.