Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/coinbase/rules_ruby

Bazel Ruby Rules
https://github.com/coinbase/rules_ruby

Last synced: 7 months ago
JSON representation

Bazel Ruby Rules

Awesome Lists containing this project

README 

          



* [Usage](#usage)

  * [WORKSPACE File](#workspace-file)

  * [BUILD.bazel files](#buildbazel-files)

* [Rules](#rules)

  * [rb_library](#rb_library)

  * [rb_binary](#rb_binary)

  * [rb_test](#rb_test)

  * [rb_bundle](#rb_bundle)

  * [rb_gem](#rb_gem)

* [What's coming next](#whats-coming-next)

* [Contributing](#contributing)

  * [Setup](#setup)

    * [OSX Setup Script](#os-setup-script)

      * [Issues During Setup](#issues-during-setup)

  * [Developing Rules](#developing-rules)

  * [Running Tests](#running-tests)

  * [Linter](#linter)

* [Copyright](#copyright)



### Build Status



| Build | Status |

|---------:	|---------------------------------------------------------------------------------------------------------------------------------------------------	|

| CircleCI Master: 	| [![CircleCI](https://circleci.com/gh/coinbase/rules_ruby.svg?style=svg)](https://circleci.com/gh/coinbase/rules_ruby) 	|



# Rules Ruby



Ruby rules for [Bazel](https://bazel.build).



** Current Status:** *Work in progress.*



Note: we have a short guide on [Building your first Ruby Project](https://github.com/coinbase/rules_ruby/wiki/Build-your-ruby-project) on the Wiki. We encourage you to check it out.



## Usage



### `WORKSPACE` File



Add `rules_ruby_dependencies` and `ruby_register_toolchains` into your `WORKSPACE` file.



```python

# To get the latest, grab the 'master' branch.



git_repository(

    name = "coinbase_rules_ruby",

    remote = "https://github.com/coinbase/rules_ruby.git",

    branch = "master",

)



load(

    "@coinbase_rules_ruby//ruby:deps.bzl",

    "ruby_register_toolchains",

    "rules_ruby_dependencies",

)



rules_ruby_dependencies()



ruby_register_toolchains()

```



Next, add any external Gem dependencies you may have via `rb_bundle` command.

The name of the bundle becomes a reference to this particular Gemfile.lock.



Install external gems that can be later referenced as `@//:`,

and the executables from each gem can be accessed as `@`

for instance, `@bundle//:bin/rubocop`.



You can install more than one bundle per WORKSPACE, but that's not recommended.



```python

rb_bundle(

  name = "bundle",

  gemfile = ":Gemfile",

  gemfile_lock = ":Gemfile.lock",

  bundler_version = "2.1.2",

  full_index = True,

)



rb_bundle(

  name = "bundle_app_shopping",

  gemfile = "//apps/shopping:Gemfile",

  gemfile_lock = "//apps/shopping:Gemfile.lock",

  bundler_version = "2.1.2",

  full_index = True,

)

```



### `BUILD.bazel` files



Add `rb_library`, `rb_binary` or `rb_test` into your `BUILD.bazel` files.



```python

load(

    "@coinbase_rules_ruby//ruby:defs.bzl",

    "rb_binary",

    "rb_library",

    "rb_test",

    "rb_rspec",

)



rb_library(

    name = "foo",

    srcs = glob(["lib/**/*.rb"]),

    includes = ["lib"],

    deps = [

      "@bundle//:activesupport",

      "@bundle//:awesome_print",

      "@bundle//:rubocop",

    ]

)



rb_binary(

    name = "bar",

    srcs = ["bin/bar"],

    deps = [":foo"],

)



rb_test(

    name = "foo-test",

    srcs = ["test/foo_test.rb"],

    deps = [":foo"],

)



rb_rspec(

    name = "foo-spec",

    specs = glob(["spec/**/*.rb"]),

    rspec_args = { "--format": "progress" },

    deps = [":foo"]

}



```



## Rules



The following diagram attempts to capture the implementation behind `rb_library` that depends on the result of `bundle install`, and a `rb_binary` that depends on both:



![Ruby Rules](docs/img/rules_ruby.png)



### `rb_library`




rb_library(name, deps, srcs, data, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, toolchains, visibility)




  

    

    

  

  

    

      Attributes

    

  

  

    

      name

      

        Name, required

        
A unique name for this rule.


      

    

    

      srcs

      

        List of Labels, optional

        


          List of .rb files.

        


        
At least srcs or deps must be present


      

    

    

      deps

      

        List of labels, optional

        


          List of targets that are required by the srcs Ruby

          files.

        


        
At least srcs or deps must be present


      

    

    

      includes

      

        List of strings, optional

        


          List of paths to be added to $LOAD_PATH at runtime.

          The paths must be relative to the the workspace which this rule belongs to.

        


      

    

    

      rubyopt

      

        List of strings, optional

        


          List of options to be passed to the Ruby interpreter at runtime.

        


        


          NOTE: -I option should usually go to includes attribute.

        


      

    

  

  

    

      And other common attributes

    

  



### `rb_binary`




rb_binary(name, deps, srcs, data, main, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, toolchains, visibility, args, output_licenses)




  

    

    

  

  

    

      Attributes

    

  

  

    

      name

      

        Name, required

        
A unique name for this rule.


      

    

    

      srcs

      

        List of Labels, required

        


          List of .rb files.

        


      

    

    

      deps

      

        List of labels, optional

        


          List of targets that are required by the srcs Ruby

          files.

        


      

    

    

      main

      

        Label, optional

        
The entrypoint file. It must be also in srcs.


        
If not specified, $(NAME).rb where $(NAME) is the name of this rule.


      

    

    

      includes

      

        List of strings, optional

        


          List of paths to be added to $LOAD_PATH at runtime.

          The paths must be relative to the the workspace which this rule belongs to.

        


      

    

    

      rubyopt

      

        List of strings, optional

        


          List of options to be passed to the Ruby interpreter at runtime.

        


        


          NOTE: -I option should usually go to includes attribute.

        


      

    

  

  

    

      And other common attributes

    

  



### `rb_test`




rb_test(name, deps, srcs, data, main, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, toolchains, visibility, args, size, timeout, flaky, local, shard_count)




  

    

    

  

  

    

      Attributes

    

  

  

    

      name

      

        Name, required

        
A unique name for this rule.


      

    

    

      srcs

      

        List of Labels, required

        


          List of .rb files.

        


      

    

    

      deps

      

        List of labels, optional

        


          List of targets that are required by the srcs Ruby

          files.

        


      

    

    

      main

      

        Label, optional

        
The entrypoint file. It must be also in srcs.


        
If not specified, $(NAME).rb where $(NAME) is the name of this rule.


      

    

    

      includes

      

        List of strings, optional

        


          List of paths to be added to $LOAD_PATH at runtime.

          The paths must be relative to the the workspace which this rule belongs to.

        


      

    

    

      rubyopt

      

        List of strings, optional

        


          List of options to be passed to the Ruby interpreter at runtime.

        


        


          NOTE: -I option should usually go to includes attribute.

        


      

    

  

  

    

      And other common attributes

    

  



### `rb_bundle`



Installs gems with Bundler, and make them available as a `rb_library`.



Example: `WORKSPACE`:



```python

git_repository(

    name = "coinbase_rules_ruby",

    remote = "https://github.com/coinbase/rules_ruby.git",

    tag = "v0.1.0",

)



load(

    "@coinbase_rules_ruby//ruby:deps.bzl",

    "ruby_register_toolchains",

    "rules_ruby_dependencies",

)



rules_ruby_dependencies()



ruby_register_toolchains()



load("@coinbase_rules_ruby//ruby:defs.bzl", "rb_bundle")



rb_bundle(

    name = "gems",

    gemfile = "//:Gemfile",

    gemfile_lock = "//:Gemfile.lock",

)

```



Example: `lib/BUILD.bazel`:



```python

rb_library(

    name = "foo",

    srcs = ["foo.rb"],

    deps = ["@gems//:all"],

)

```



Or declare many gems in your `Gemfile`, and only use some of them in each ruby library:



```python

rb_binary(

    name = "rubocop",

    srcs = [":foo", ".rubocop.yml"],

    args = ["-P", "-D", "-c" ".rubocop.yml"],

    main = "@gems//:bin/rubocop",

    deps = ["@gems//:rubocop"],

)

```




rb_bundle(name, gemfile, gemfile_lock, bundler_version = "2.1.2")




  

    

    

  

  

    

      Attributes

    

  

  

    

      name

      

        Name, required

        
A unique name for this rule.


      

    

    

      gemfile

      

        Label, required

        


          The Gemfile which Bundler runs with.

        


      

    

    

      gemfile_lock

      

        Label, required

          
The Gemfile.lock which Bundler runs with.


          
NOTE: This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock


      

    

    

      bundler_version

      

        String, optional

          
The Version of Bundler to use. Defaults to 2.1.2.


          
NOTE: This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock


      

    

    

      full_index

      

        Bool, optional

          
Set to True to add the --full-index option to the bundle install. Can improve performance.


      

    

  



## rb_gem

Used to generate a zipped gem containing its srcs, dependencies and a gemspec.




rb_gem(name, gem_name, version, srcs, authors, deps, data, includes)




  

    

    

  

  

    

      Attributes

    

  

  

    

      name

      

        Name, required

        
A unique name for this rule.


      

    

    

      gem_name

      

        Name of the gem, required

        
The name of the gem to be generated.


      

    

    

    

      version

      

        Label, required

        


          The version of the gem. Is used to name the output file,

          which becomes name-version.zip, and also

          included in the Gemspec.

        


      

    

    

      authors

      

        List of Strings, required

        


          List of human readable names of the gem authors.

          Required to generate a valid gemspec.

        


      

    

    

      srcs

      

        List of Labels, optional

        


          List of .rb files.

        


        
At least srcs or deps must be present


      

    

    

      deps

      

        List of labels, optional

        


          List of targets that are required by the srcs Ruby

          files.

        


        
At least srcs or deps must be present


      

    

  



## What's coming next



1. Building native extensions in gems with Bazel

2. Using a specified version of Ruby.

3. Releasing your gems with Bazel



## Contributing



We welcome contributions to RulesRuby.



You may notice that there is more than one Bazel WORKSPACE inside this repo. There is one in `examples/simple_script` for instance, because

we use this example to validate and test the rules. So be mindful whether your current directory contains `WORKSPACE` file or not.



### Setup



#### OSX Setup Script



You will need Homebrew installed prior to running the script.



After that, cd into the top level folder and run the setup script in your Terminal:



```bash

❯ bin/setup-darwin

```

##### Issues During Setup



**Please report any errors as Issues on Github.**



### Developing Rules



Besides making yourself familiar with the existing code, and [Bazel documentation on writing rules](https://docs.bazel.build/versions/master/skylark/concepts.html), you might want to follow this order:



  1. Setup dev tools as described in the [setup](#Setup) section.

  3. hack, hack, hack...

  4. Make sure all tests pass — you can run individual Bazel test commands from the inside.



   * `bazel test //...`

   * `cd examples/simple_script && bazel test //...`



  4. Open a pull request in Github, and please be as verbose as possible in your description.



In general, it's always a good idea to ask questions first — you can do so by creating an issue.



### Running Tests



After running setup, and since this is a bazel repo you can use Bazel commands:



```bazel

bazel build //...:all

bazel query //...:all

bazel test //...:all

```



But to run tests inside each sub-WORKSPACE, you will need to repeat that in each sub-folder.



### Linter



We are using RuboCop for ruby and Buildifier for Bazel. Both can be run using bazel:



```bash

bazel run //:buildifier

```



## Copyright



© 2018-2019 Yuki Yugui Sonoda & BazelRuby Authors



Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at



Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.