lib-ruby-parser 4.0.3.0-arm64-darwin

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: dc794d4bcd84e7b52c04316d31c1bb107ac738c7b1f4d74cbd04882a5d7fb035
4
+ data.tar.gz: e9e4e1e41c4a2f8f6769305809f162cbc410ddbe52b9513b677f706d3c25bfee
5
+ SHA512:
6
+ metadata.gz: dd76b3f173c4e061d069074137edf6beed8538e8b1b637e24c0e9c8712c06021a473c52ecf031247225deb935ee8aa39da7cd310cac997b4cb24684906570c2b
7
+ data.tar.gz: d5f47d13ccf6794648ba446551f769389e16682ca927de35cc60b6a35ff17ae6904dea5e01ef2eed60179ff42b7db7742d56d4ef9c39ccb69686a1684f227125
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.