Add a documentation section explaining the custom bundle

[vinistock]

The custom bundle is sometimes a source of confusion. Users don't always realize why it's necessary or how it is supposed to work.

The fact that we hide the .ruby-lsp directory automatically in VS Code, makes it even more obscure if something is not working right.

Let's add a new README section explaining what the custom bundle is and how it works. And let's mention that the extension automatically hides the directory.

[cmolina]

I think the problem here is that the name of the setting, rubyLsp.customRubyCommand is misleading.

By just reading the name of the property, I assumed I had to set it to the path of my ruby executable (in my case is /nix/store/1v7fqs5ihrp6l44sncsji32c64ldgsvy-ruby-3.2.2/bin/ruby). But that didn't work, the extension was stuck with no errors.

Then when I read skimmed the description

A shell command to activate the right Ruby version or add a custom Ruby bin folder to the PATH

I tried to pass the directory instead /nix/store/1v7fqs5ihrp6l44sncsji32c64ldgsvy-ruby-3.2.2/bin/. At least that failed with an error.

Eventually, when I read the full description, I understood that I had to pass a command that makes ruby available. In my case I am using nix and direnv, so direnv allow was enough.

---

It would be nice if:

• I don't need to change the version manager, just setting up ruby
• The property for setting up ruby has a better name; here are a few examples customActivate, executableThatAddsRubyToPATH, cmdToSetupRuby
• The description of the property includes an example

[GrantBirki]

The custom bundle is sometimes a source of confusion

I am currently in the "confused realm". I am trying to use ruby-lsp in a project with a bundle. The bundle contains Gems that are in an internal GitHub RubyGems package registry. Additionally, I have Gems that are vendored in my project's vendor/cache directory. The ruby-lsp server is just continuously crashing and I'm not certain how to alter my project's custom bundle to resolve the issue.

[vinistock]

@cmolina thank you for the report. I should mention that this issue is to document the custom bundle, not the custom activation command, which are different things.

Regarding your points

I don't need to change the version manager, just setting up ruby

What do you mean by setting up Ruby? Simply pointing to a Ruby installation is often not enough and might not work on every setup. Version managers activate multiple environment variables, so that the NodeJS process knows where to look for Ruby, Bundler and where gems are installed. For example:

# Asking for where gems are installed using Ruby 2.7.6

/opt/rubies/2.7.6/bin/ruby -rbundler -e "puts Bundler.bundle_path"

# If a version manager previously activated environment variables such as `GEM_HOME`, then
# this actually prints

~/.gem/ruby/3.2.2

# If nothing was activated by any version manager, then this may print the system Ruby
/Library/Ruby/Gems/2.6.0

# And both paths are incorrect

Without adequate activation of gem paths, launching the server won't work. And you are using an environment manager, it's direnv that's likely activating the right environment variables you need.

The property for setting up ruby has a better name; here are a few examples customActivate, executableThatAddsRubyToPATH, cmdToSetupRuby
The description of the property includes an example

Yeah, the name may not be the clearest indeed. The description field is not intended for that, but there's an examples field for configurations that we can definitely add.