lib-ruby-parser 0.0.1.beta1-x86_64-darwin

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: e578fa7b3dede2c0efb0e39df093fae3ffb95e8dea95a45a0800ef99d01f2b28
4
+ data.tar.gz: b70b19d7d9c6b96d45f3d49df58a6e7989635515189cbb43051d5243d0734134
5
+ SHA512:
6
+ metadata.gz: 6a5611df0cd3309915b4f66fd00fadf695e83150d90ae6b253a3272f059bac42e78cade622a5a6a4e69e8b0e09789a70f61546703b5737a454d3f242c0f7d10f
7
+ data.tar.gz: eb8f18f387735fcd5052e17c871bb6d01b2c8787e8d21eaa6f67f218960773b22f40b8879edce68a2466a7fa080489f771d0eb1f6dcc169ab3a588d509b49284
data/README.md ADDED
@@ -0,0 +1,122 @@
1
+ # LibRubyParser
2
+
3
+ Ruby bindings for [`lib-ruby-parser`](https://github.com/lib-ruby-parser/lib-ruby-parser)
4
+
5
+ ## Installation
6
+
7
+ Add this line to your application's Gemfile:
8
+
9
+ ```ruby
10
+ gem 'lib-ruby-parser'
11
+ ```
12
+
13
+ And then execute:
14
+
15
+ $ bundle install
16
+
17
+ Or install it yourself as:
18
+
19
+ $ gem install lib-ruby-parser
20
+
21
+ ## Usage
22
+
23
+ Basic usage:
24
+
25
+ ```ruby
26
+ require 'lib-ruby-parser'
27
+
28
+ input = <<~RUBY
29
+ def foo(a, b, c)
30
+ a + b + c
31
+ end
32
+ RUBY
33
+
34
+ result = LibRubyParser.parse(input, {})
35
+ pp result
36
+ ```
37
+
38
+ Full documentation can be found [here](https://lib-ruby-parser.github.io/ruby-bindings/)
39
+
40
+ ## Development
41
+
42
+ This repo is **mostly** based on [`c-bindings`](https://github.com/lib-ruby-parser/c-bindings) and [`lib-ruby-parser-nodes Rust crate`](https://github.com/lib-ruby-parser/nodes)
43
+
44
+ 1. `c-bindings` directory contains static library and header file from the latest [c-bindings release](https://github.com/lib-ruby-parser/c-bindings/releases). Both header and static lib are under gitignore.
45
+ 2. `codegen` directory is a Rust micro-library that generates:
46
+ + `nodes.h` - header file with C -> Ruby conversion functions for all `Node` types
47
+ + `messages.h` - header file with C -> Ruby conversion functions for all `DiagnosticMessage` types
48
+ + `lib/lib-ruby-parser/nodes.rb` - classes and documentation for all `Node` types
49
+ + `lib/lib-ruby-parser/messages.rb` - classes and documentation for all `DiagnosticMessage` types
50
+ 3. `lib` directory contains classes and documentation for all classes except dynamic nodes and diagnostic messages
51
+ 4. `main.c` is the main entrypoint to C world. It defines a single `LibRubyParser.parse` function that converts given Ruby objects, converts them to C equivalent, calls `LIB_RUBY_PARSER_parse` from `c-bindings` and converts returned C objects back to Ruby objects. 90% function names in `main.c` end with either `__from_ruby` (to convert object from Ruby to C) or `__to_ruby` (to convert C -> Ruby).
52
+ 5. `scripts` directory:
53
+ 1. `scripts/targets` - directory with target- (and in our case OS-) specific configurations
54
+ 2. `scripts/compile.rb` - prints code to compile `main.c` to `main.o`
55
+ 3. `scripts/link.rb` - prints code to link `main.o` to `lib/lib-ruby-parser/native/lib_ruby_parser.$(DYLIB_EXT)`
56
+ 4. `scripts/setup.mk` - basic setup, prints debug information, auto-included by root Makefile
57
+ 6. `test` directory contains a single minitest test that performs a smoke test
58
+
59
+ To run it locally:
60
+
61
+ 1. make sure to have Ruby and Rust
62
+ 2. `git clone` the repo
63
+ 3. run `bundle install`
64
+ 4. run `make test`
65
+
66
+ ## Safety
67
+
68
+ `c-bindings` is tested with Address Sanitizer (ASAN) on every commit, so it's clean from memory leaks.
69
+
70
+ We do run ASAN on CI on every commit for this repo too, but enabling it is a bit tricky. Ruby executable is not linked with `libasan.so`, and so if `main.c` is compiled with `-fsanitize=address` loading `lib_ruby_parser.dylib` gives an error at runtime, `malloc` is supposed to "track itself" using `libasan.so` functionality, but it's not available. `LD_PRELOAD` (on Linux) and `DYLD_INSERT_LIBRARIES` (on MacOS) can do the trick.
71
+
72
+ 1. On Linux:
73
+ + Pass `CFLAGS="-fsanitize=address"` to `make test` to get `lib/lib-ruby-parser/native/lib_ruby_parser.so` compiled with ASAN
74
+ + Get path to `libasan.so` by running `gcc -print-file-name=libasan.so`
75
+ + Pass it to `make test` with `LD_PRELOAD=$(gcc -print-file-name=libasan.so) make test`
76
+ 2. On MacOS:
77
+ + Make sure to have `clang` installed with Homebrew, default `clang` that ships with MacOS doesn't have it.
78
+ + Pass `CC=clang CFLAGS="-fsanitize=address"` to `make test` to get `lib/lib-ruby-parser/native/lib_ruby_parser.bundle` compiled with ASAN
79
+ + Get path to `libclang_rt.asan_osx_dynamic.dylib` by running `clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib`
80
+ + Pass it to `make test` with `DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) make test`
81
+
82
+ CI does the same thing on every commit.
83
+
84
+ Additionally, we run Leak Sanitizer (LSAN) that is a part of ASAN, it can be enabled by setting `ASAN_OPTIONS=detect_leaks=1` env var.
85
+
86
+ Unfortunately, Ruby does something that makes LSAN complain no matter what:
87
+
88
+ ```
89
+ ASAN_OPTIONS=detect_leaks=1 \
90
+ DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) \
91
+ ruby -e 'p 1'
92
+
93
+ # prints a TON of leaks leaks
94
+ Direct leak of 48 byte(s) in 1 object(s) allocated from:
95
+ #0 0x108e0fb25 in wrap_calloc+0xa5 (libclang_rt.asan_osx_dynamic.dylib:x86_64+0x44b25)
96
+ #1 0x1098cfab4 in ruby_xcalloc_body+0x214 (libruby.3.0.dylib:x86_64+0xd0ab4)
97
+ #2 0x109a6dfb2 in rb_method_entry_make+0x3a2 (libruby.3.0.dylib:x86_64+0x26efb2)
98
+ #3 0x109a6cfd8 in rb_add_method+0x38 (libruby.3.0.dylib:x86_64+0x26dfd8)
99
+ #4 0x109a6cf3e in rb_add_method_cfunc+0x3e (libruby.3.0.dylib:x86_64+0x26df3e)
100
+ #5 0x1098f2efc in Init_IO+0x134c (libruby.3.0.dylib:x86_64+0xf3efc)
101
+ #6 0x1098ea7c4 in rb_call_inits+0x94 (libruby.3.0.dylib:x86_64+0xeb7c4)
102
+ #7 0x1098b61e7 in ruby_setup+0x137 (libruby.3.0.dylib:x86_64+0xb71e7)
103
+ #8 0x1098b6268 in ruby_init+0x8 (libruby.3.0.dylib:x86_64+0xb7268)
104
+ #9 0x108db7ef8 in main+0x48 (ruby:x86_64+0x100003ef8)
105
+ #10 0x7fff203baf3c in start+0x0 (libdyld.dylib:x86_64+0x15f3c)
106
+ ```
107
+
108
+ It is possible to suppress specified leaks, we have `LSan.supp` file for that:
109
+
110
+ ```
111
+ LSAN_OPTIONS=suppressions=LSan.supp \
112
+ ASAN_OPTIONS=detect_leaks=1 \
113
+ DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) \
114
+ ruby -e 'p 1'
115
+ # prints nothing
116
+ ```
117
+
118
+ We use the same file on CI, no functions from `lib-ruby-parser` are allowed to produce leaks.
119
+
120
+ ## Contributing
121
+
122
+ Bug reports and pull requests are welcome on GitHub at https://github.com/lib-ruby-parser/ruby-bindings.