Week 1 & 2- CircuitVerse@GSOC'23

Community Bonding Period

This was a long time between getting the selection mail and the coding period. It allows me to learn more about some toolkits and libraries in detail required for this project. During this period, we have a couple of online discussions with the mentors to discuss the timeline [if any changes are required] and some topics of the project on which I will work in the coming weeks.

Officially the coding period begins on 29th May 2023

The main goal of these two weeks

Integrate Ruby Debugger Support
Integrate Solargraph LSP

And both the integrations should be compatible with the local setup as well as the docker container-based development setup

Integrate Ruby Debugger

Purpose - Currently this project has byebug gem for debugging purposes. Ruby has released its official debugger debug gem which works with various IDEs flawlessly with the visual interface which makes it very easy for developers and contributors to debug the application.

Implementation -

Install debug gem in the project.

Now, we can debug our application with VSCode with local installation by running this command

 bundle exec rdbg --open --nonstop --command -- bundle exec rails server -p 3000This will start the rails server and will attach the debugger with that process.

For debugging with VSCode, install the vscode-rdbg extension from marketplace.

Use v1.0.0 of this extension as the v2.0.0 version has some bugs. The bug has been fixed but the new version has yet not released

Now, in the VSCode we need to provide the settings for the debugger.

{
    "version": "0.1.0",
    "configurations": [
        {
            "type": "rdbg",
            "name": "Attach Debugger",
            "request": "attach"
        }
    ]
}

Now, we can attach to this and set breakpoints and debug the application.

We can also, debug the application with Chrome by providing --open=chrome option.

  bundle exec rdbg -n --open=chrome --command -- bundle exec rails server -p 3000

Now, we have two choices for debugging - any IDE or Chrome

To make it convenient for end-user,

Created two files Procfile.dev for IDEs and Procfile.chrome.dev for chrome-based debugging
In the /bin/dev file added chrome_debug flag check. If user provides chrome_debug flag while running the command it will open chrome for debugging else it will allow IDE to attach to the debugger
/bin/dev for default mode and /bin/dev chrome_debug for chrome-based debugging

Make it compatible with a docker-based setup :

To accomplish this, we use the TCP-based remote debugging feature of debug gem.

In the dev/docker_run we put the command for socket-based debugging by providing host and port [3001]

bundle exec rdbg  --nonstop --open --host 0.0.0.0 --port 3001 -c -- bundle exec rails s -p 3000 -b '0.0.0.0'

So, now the debugger client can attach to the 3001 port and debug the application.

Now we need to expose the port by specifying the port mapping in the docker-compose.yml file

ports:
  - "3000:3000"
  - "3001:3001"

But, in the VSCode we need to add separate config for the debugger client to attach to tcp based remote debugging server

{
  "type": "rdbg",
  "name": "(Docker) Attach debugger [:3001]",
  "request": "attach",
  "debugPort": "localhost:3001",
  "showProtocolLog": true,
  "localfsMap": "/circuitverse:${workspaceFolder}"
}

🏂 Now this setup will allow debugging with VSCode or Chrome or Any other supported IDE with both local and Docker-based installation

Issues & Fixes -

During the integration, initially, it was failing as the Puma was configured to run multiple web workers at a time. For this, the debugger server process also got multiplied and want to start multiple processes either on the same Unix port or the same TCP port and the processes failed.

To resolve the issue, we change the default value of WEB_CONCURRENCY in /config/puma.rb to 0 for the development environment

This fixes the problem.

Pull Request - github.com/CircuitVerse/CircuitVerse/pull/3..

Integrate Solargraph LSP

Purpose - Currently, in this project, no Language Server is configured so we can't utilise autocomplete feature of IDE. The project is built on the Ruby on Rails framework which has used metaprogramming too much. So by default, the LSPs can't provide autocomplete or suggestions. So we have planned to integrate Solargraph as a Language Server to enable autocompletion and make it convenient for other contributors while working on this project.

Implementation -

The main gem for this solargraph LSP is solargraph .

We need to write the yard docs for the codebase to enable auto-completion. But in Rails, there are ActiveRecord models and many abstract classes which will make it complex to write yard docs for those. So, there is another gem [kind of extension of solargraph gem] called solargraph-rails which allows us to easily add yard docs for the ActiveRecord models.

We can learn how to write the yard docs from this documentation.

After completion of writing yard docs, we can enable this for many IDEs by the following guide

In VSCode, we can install ruby solargraph extension and got the autocompletion instantly.

For NeoVim, check out this discussion thread

For Sublime Text Editor, check out this discussion thread

For local setup, this works without any issues.

But now we need to make it compatible with a docker-based setup.

Here we utilize the TCP socket-based LSP server feature. Inside the container, we start the solargraph LSP server at port 3002 and expose it to the host

solargraph socket --host=0.0.0.0 --port=3002

Now, in the VSCode or other IDEs, we can configure to use this external solargraph server.

But here an issue comes, The plugin of IDE or Code Editor sends the current path of the file to the LSP server. The container and the current host directory is different, so the LSP fails to resolve and provide autocompletion.

To resolve this issue, I take this approach.

Pass the current directory to the container by using the environment variable
- In docker-compose, we can use $PWD to know the current directory path
In the container, create a symlink at $PWD which points to /circuitverse/ in the container

Visual Representation

Thus the path inside the container resolves and the solargraph provides the autocompletion without any issue.

Checkout the PR, to know more about this approach