{"id":28615577,"url":"https://github.com/ocamlpro/superbol-studio-oss","last_synced_at":"2025-06-12T02:09:29.004Z","repository":{"id":162647938,"uuid":"622873107","full_name":"OCamlPro/superbol-studio-oss","owner":"OCamlPro","description":"Open-Source part of SuperBOL Studio, including the Visual Studio Code extension and its LSP server","archived":false,"fork":false,"pushed_at":"2025-05-22T12:49:52.000Z","size":41748,"stargazers_count":32,"open_issues_count":62,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-22T14:24:52.997Z","etag":null,"topics":["cobol","emacs-mode","lsp-server","vscode-extension"],"latest_commit_sha":null,"homepage":"https://superbol.eu","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OCamlPro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-03T08:33:34.000Z","updated_at":"2025-05-22T12:33:26.000Z","dependencies_parsed_at":"2023-09-15T04:43:05.498Z","dependency_job_id":"9b17d910-cd66-47f0-9c99-1a914ab825a7","html_url":"https://github.com/OCamlPro/superbol-studio-oss","commit_stats":null,"previous_names":["ocamlpro/superbol-vscode-platform","ocamlpro/superbol-studio-oss"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/OCamlPro/superbol-studio-oss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fsuperbol-studio-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fsuperbol-studio-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fsuperbol-studio-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fsuperbol-studio-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OCamlPro","download_url":"https://codeload.github.com/OCamlPro/superbol-studio-oss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCamlPro%2Fsuperbol-studio-oss/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259382322,"owners_count":22848842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobol","emacs-mode","lsp-server","vscode-extension"],"created_at":"2025-06-12T02:09:28.129Z","updated_at":"2025-06-12T02:09:28.969Z","avatar_url":"https://github.com/OCamlPro.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SuperBOL Studio OSS: A New Platform for COBOL\n\n[![Actions Status](https://github.com/ocamlpro/superbol-studio-oss/workflows/Main%20Workflow/badge.svg)](https://github.com/ocamlpro/superbol-studio-oss/actions)\n[![Release](https://img.shields.io/github/release/ocamlpro/superbol-studio-oss.svg)](https://github.com/ocamlpro/superbol-studio-oss/releases)\n[![Tag](https://img.shields.io/github/tag/ocamlpro/superbol-studio-oss.svg)](https://github.com/ocamlpro/superbol-studio-oss/tags)\n\nVisual Studio Code extension for COBOL.\n\n## Getting started\n\n### Installation\n\nYou can install SuperBOL Studio OSS either directly from within VS\nCode, or via a VSIX file.\n\n#### Installation within VS Code\n\nFirst, click on the \"Extensions\" icon in the activity bar on the\nleft-hand side, or press\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eX\u003c/kbd\u003e.  Then, type \"superbol\"\ninto the search bar to find it, and press its `Install` button.\n\nYou can find further instructions for installing extensions directly\nwithin VS Code on [this\npage](https://code.visualstudio.com/docs/editor/extension-marketplace).\n\n#### Installation via a VSIX file\n\nFirst, download a VSIX file from the\n[Marketplace](https://marketplace.visualstudio.com/items?itemName=OCamlPro.SuperBOL)\nor [Open VSX](https://open-vsx.org/extension/OCamlPro/SuperBOL).\n\nTo install the extension from its VSIX file, open VS Code and go to\nthe the \"Extensions\" view.  In the sidebar, click on the three dots\n(`⋅⋅⋅`) on the top right-hand side (just above `search`), select\n`Install from VSIX…`.  Pick the VSIX file you just downloaded to\ninstall it.\n\n### Editing an existing project\n\nTo start using the extension on an existing project, open its folder\nin VS Code (`File \u003e Add Folder to Workspace…`).  The extension will\nstart automatically whenever the folder contains files with usual\nCOBOL filename extensions (`.cob`, `.cbl`, `.cpy`, `.cbx`).\n\nThen, open the settings (`File \u003e Preferences \u003e Settings`, or\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003e,\u003c/kbd\u003e), and start typing \"superbol…\".  You will\nbe presented with a screen that resembles:\n\n![SuperBOL settings](./assets/superbol-settings.png)\n\nFrom here, you can notably configure:\n\n- The COBOL dialect used in the project `\"superbol.cobol.dialect\"` (see\n  [here](https://get-superbol.com/gnucobol/manual/chapter2.html#configuration-options)\n  for a documentation on every available dialect).  \n  In SuperBOL, the `default` dialect corresponds to GnuCOBOL's default, that supports\n  many features from dialects such as `COBOL2014`, `IBM`, `Micro\n  Focus` (`mf`), or `GCOS` for instance;\n\n- The default reference source-format `\"superbol.cobol.sourceFormat\"` (see\n  [here](https://get-superbol.com/gnucobol/manual/chapter2.html#source-format)\n  for a documentation on the supported source formats).  \n  When `auto` is selected, which is the default, SuperBOL (and GnuCOBOL) will\n  automagically try to guess whether the source is in `free` or\n  `fixed` format.  Other source formats need to be configured\n  explicitly.\n\n- The path to copybooks `\"superbol.cobol.copybooks\"`.  \n  To configure this setting, you will need to select `Edit in settings.json`. This is\n  a list, where each entry describes an element of the search path where your\n  copybooks will be looked for.  Each entry must contain a directory name `dir`,\n  and may feature an optional `file-relative` flag.  When absent or set to\n  `false`, the latter field indicates that the directory name is\n  either absolute, or relative to the root of the project's directory.\n  When `file-relative` is `true`, the element of the search path is\n  considered relative to the directory where each main source program\n  is located.\n\n  ![Editing copybook paths in `.vscode/settings.json`](./assets/superbol-editing-copybooks-path-in-vscode-settings.png)\n\n- The copybook extensions `\"superbol.cobol.copyexts\"`.  \n  To configure this setting, you will need to select `Edit in settings.json`. This is\n  a list, where each entry describes a file extension if the copybook name cannot\n  be found as-is (for example `COPY \"mycpy.lib\"`).\n  In SuperBOL, the `default` option corresponds to GnuCOBOL's default, which\n  is `\"cpy\"`, `\"cbl\"`, and `\"cob\"` (searched in upper-case first, and then in\n  lower-case).\n\n## Syntax diagnostics\n\n\u003e [!NOTE]\n\u003e\n\u003e Syntax checks performed by SuperBOL Studio currently cover the\n\u003e `COBOL85` dialect, and some constructions of more recent dialects\n\u003e supported by GnuCOBOL.  Reporting of such diagnostics is currently\n\u003e disabled for dialects other than `COBOL85` to avoid misleading\n\u003e developers with false diagnostics about syntax errors.\n\u003e\n\u003e Reporting can be re-enabled for every dialect by setting the `Force\n\u003e Syntax Diagnostics` flag in SuperBOL configuration settings.\n\n## IntelliSense (auto-completion)\n\nWhen editing a program, you can press \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eSpace\u003c/kbd\u003e\nto obtain suggestions on valid keywords, user-defined words (data item\nor paragraph names), and even complete COBOL sentences.  Select an\noption with the arrow keys, and press \u003ckbd\u003eEnter\u003c/kbd\u003e to insert the\nselected suggestion.\n\n![IntelliSense sentence](./assets/superbol-completion-data-div-sentence.gif)\n![IntelliSense data item](./assets/superbol-completion-data-item.png)\n![IntelliSense paragraph](./assets/superbol-completion-paragraph.png)\n\n\u003e [!NOTE]\n\u003e (Temporary limitation)\n\u003e\n\u003e Suggestions of user-defined words may not comprise symbols that are\n\u003e defined in the communication, report, or screen section of the data\n\u003e division.  Although user-defined words that occur in [configured\n\u003e copybooks](#editing-an-existing-project) are also suggested,\n\u003e preprocessor-related variables or phrases are not.\n\n## Navigation features\n\n### Outline \u0026 Breadcrumbs\n\nSuperBOL provides an outline view of your program once you open it,\nthat you can use to navigate to specific sections or symbols (data\nitems, paragraphs, etc).  The same information is also shown in the\n[\"breadcrumbs\"](https://code.visualstudio.com/docs/editor/editingevolved#_breadcrumbs)\nbar, that is usually located above the text edition area.\n\n![Outline \u0026 Breadcrumb](./assets/superbol-outline.png)\n\n### Go to Symbol\n\nSymbols shown in Outline and Breadcrumbs views can also be searched\nand jumped to by pressing\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eO\u003c/kbd\u003e.\n\n![Go to Symbol](./assets/superbol-goto-symbol.gif)\n\n### Go to Definition\n\nWhen you want to locate the definition of a data item name in your\nsource code, position your cursor on its name, right click, and\nselect  `Go to Definition` (or press \u003ckbd\u003eF12\u003c/kbd\u003e).\n\n![Go to Definition](./assets/superbol-goto-definition.gif)\n\n\u003e [!NOTE]\n\u003e (Temporary limitation)\n\u003e\n\u003e At the moment, definitions that belong to communication, report, or\n\u003e screen sections of the data division are ignored by the extension.\n\u003e In addition, some definitions in embedded SQL blocks (`EXEC SQL`)\n\u003e are not taken into account yet.\n\n### Peek Definition\n\nTo only have a peek at where such a data item defined, you can\nposition the cursor on its name, right click, and select  `Peek \u003e Peek\nDefinition` (or press\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eF10\u003c/kbd\u003e).  You will then be\npresented with a view of the location of the corresponding definition,\nincluding if it lies in a copybook.\n\n![Peek Definition in copybook](./assets/superbol-peek-at-definition-in-copybook.gif)\n\n### Go to References\n\nIf you want to obtain a list of all references to a named data item,\nright click and select  `Go to References` (or press\n\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eF12\u003c/kbd\u003e).  You will then view the location of\nevery reference to this item.\n\n![Go to References](./assets/superbol-goto-references.gif)\n\n\u003e [!NOTE]\n\u003e (Temporary limitation)\n\u003e\n\u003e Limitations mentioned in [Go to Definition](#go-to-definition) also\n\u003e apply.\n\n### Reference Information\n\nThe extension shows inline reference information above definitons of\ndata items and elements of the procedure division.  \nThe same limitations as for [Go to Definition](#go-to-definition)\napply.\n\n![Reference Information](./assets/superbol-reference-information.png)\n\n\u003e [!TIP]\n\u003e \n\u003e This feature can be turned on or off by tuning the\n\u003e `\"editor.codeLens\"` configuration setting (you can type\n\u003e \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003e,\u003c/kbd\u003e and then `codelens` to change this\n\u003e setting).\n\n### Hover to Show Copybooks\n\nEver wondered what was behind a `COPY` directive?  Just position your\ncursor over such a statement, and you will be presented with the\ncontents of the copybook.\n\n![Hover over `COPY`](./assets/superbol-hover-copy.png)\n\nTo ensure this works correctly, check your `\"superbol.cobol.copybooks\"`\nand `\"superbol.cobol.copyexts\"` settings.\n\n### Hover to Show Source Text Replacements\n\nWhat's more?  You can see the source text that results from\nreplacement by a `REPLACE` directive in the same way.\n\n![Hover over replacement](./assets/superbol-hover-replacement.gif)\n\n## Editing\n\n### Rename Data Items, Sections, and Paragraphs\n\nYou can rename any data item by pressing \u003ckbd\u003eF2\u003c/kbd\u003e while your\ncursor is positioned on one of its references.  The extension will\nwarn you if a reference to the renamed item appears in a copybook (in\nwhich case the renaming of every reference is not performed).\n\n![Rename Symbol](./assets/superbol-rename-symbol.gif)\n\n![Rename Symbol in Copybook](./assets/superbol-rename-symbol-in-copybook.gif)\n\nSections and paragraphs of the procedure division can also be renamed\nin the same way.  \nThe same limitations as for [Go to References](#go-to-references)\napply to this feature.\n\n## Exploring the Control-flow\n\nNavigating a graphical representation of a COBOL program's\ncontrol-flow proves invaluable when it comes to decipher its overall\nlogic.  To do this, open the command palette (or type\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e), and select `SuperBOL:\nShow Control-flow` (you can also right click and select `Show\nControl-flow` in the menu).  You are then presented with a list of\nportions of program to consider (either the entire program, or\nindividiual sections): select one element to see the corresponding\nCFG.\n\n![CFG Explorer](./assets/superbol-cfg-explorer.gif)\n\nVarious settings are provided to tune the rendering of CFGs.\n\n![CFG Explorer Collapse Fallthrough](./assets/superbol-cfg-explorer-collapse-fallthrough.gif)\n\n### CFG as an arc diagram\n\nA rendering of CFGs as arc diagrams is also available.  In this\nrepresentation, named sections and paragraphs are laid out vertically,\nand arcs show the direction of control-flow between them.\n\n![CFG Explorer as Arc Diagram](./assets/superbol-cfg-explorer-arc.gif)\n\n## Debugging\n\nIn order to debug a COBOL program, you first need to run a *build\ntask* with appropriate debug options.  Once this is done, you can\n*launch* the compiled program in a debugging session.\n\n\u003e [!NOTE]\n\u003e\n\u003e We recommend that a version of\n\u003e [GnuCOBOL](https://sourceforge.net/projects/gnucobol/) that is at\n\u003e least as recent as version 3.2 be available on the system running VS\n\u003e Code.  Debug and coverage features respectively assume that\n\u003e [gdb](https://sourceware.org/gdb/) and\n\u003e [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) are installed.\n\u003e\n\u003e On Windows systems, users may employ dedicated installers that are\n\u003e available [here](https://get-superbol.com/software/gnucobol-aio/).\n\u003e Linux users may rely on their favorite package manager and install\n\u003e `gnucobol`.\n\n### Running a Build Task for Debugging\n\nAfter having opened the program to debug, select `Terminal \u003e\nRun Build Task…`  (\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eB\u003c/kbd\u003e), and\nthen `SuperBOL: build (debug)`.\n\n![Select `SuperBOL: build (debug)`](./assets/superbol-configure-build-tasks.png)\n\n### Launching the Compiled Program for Debugging\n\nIf needed, you can place a breakpoint on statements (or paragraph\ntitles in the procedure division) by clicking on the red dot that\nappears when you hover the cursor on the left margin (or with\n\u003ckbd\u003eF9\u003c/kbd\u003e).  Click on the red dot or press \u003ckbd\u003eF9\u003c/kbd\u003e again to\nremove a breakpoint.  Then, to launch the program in debug mode,\nselect `Run \u003e Start Debugging` (\u003ckbd\u003eF5\u003c/kbd\u003e).  This will run your\nprogram until a first breakpoint if reached, or to completion.\n\n![Start Debugging](./assets/superbol-start-debugging.gif)\n\nOnce stopped on a breakpoint, you can investigate the values of data\nitems from the program using the `VARIABLES` panel on the left-hand\nside.\n\nPress \u003ckbd\u003eF10\u003c/kbd\u003e to step to the next statement, or \u003ckbd\u003eF5\u003c/kbd\u003e\nagain to continue until the next breakpoint, or termination of the\nprogram.\n\n### Customizing Build Tasks\n\nTo customize a build task, you can select `Terminal \u003e Configure\nDefault Build Task…`, and then `SuperBOL: build` or\n`SuperBOL: build (debug)` (the latter being the task that is run\nwhenever you start a debugging session, *e.g* with \u003ckbd\u003eF5\u003c/kbd\u003e).\n\nSave the `tasks.json` as shown.  Definitions for this task notably\ninclude a `forDebug` flag, that instructs the compiler to insert debug\nannotations into generated executable files (this effectively passes\nflags `-ftraceall` and `-g` to `cobc`).  The `extraArgs` setting can\nbe edited to pass additional arguments to `cobc`.\n\n![`tasks.json` for debug](./assets/superbol-tasks.json.png)\n\n## Coverage\n\nGnuCOBOL can instrument your programs so they can generate coverage\ninformation at runtime.  To enable this feature, you can set the\n`forCoverage` setting to `true` in the `Superbol: build (debug)` task\nin your `tasks.json` file (see [Customizing Build\nTasks](#customizing-build-tasks)).  This flag instructs the extension\nto pass the `--coverage` flag to the `cobc` compiler.\n\n### Coverage Information\n\nGenerated coverage files are in [`gcov`\nformat](https://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html); they are\nportable, and you can use them as you would any other coverage file\ngenerated for programs written using other programming languages.\n\n### Highlighting Coverage Information\n\nCoverage data can be shown after the execution of a program that was\ncompiled to generate this information terminates.  SuperBOL will\ndisplay coverage on a line-by-line basis, by highlighting the lines of\nyour source code using colors that represent their coverage status.\nTo enable coverage highlighting, you can open the command palette (or\ntype \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e), and select\n`SuperBOL: Show Coverage`.  You can also hide the highlighting with\nthe command `SuperBOL: Hide Coverage`, and update it after\nre-executing your program with `SuperBOL: Update Coverage`.\n\n![Show Coverage](./assets/superbol-show-coverage.png)\n\n\u003c!-- ## Formatting the source code --\u003e\n\n\u003c!-- \u003e [!NOTE] --\u003e\n\u003c!-- \u003e --\u003e\n\u003c!-- \u003e Not working on the NIST-COBOL85 suite. --\u003e\n\n## Miscellaneous\n\n### Collaborating with other developers\n\nAt this point, the settings for your project are stored and managed by\nVS Code.  However, you may plan to collaborate with developers that do\nnot use this editor.  For instance, they might want to use our mode\nfor GNU/Emacs, which is located [here](./emacs/).  Then, we advise you\nto let SuperBOL Studio store the configuration in a `superbol.toml`\nfile that will be located at the root of the project.\n\nYou can make the extension write your current project configuration\ninto a `superbol.toml` by entering the command palette (`View \u003e\nCommand Palette…`, or press\n\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eShift\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e), and then selecting the\ncommand `SuperBOL: Write Project Configuration`.\n\n![SuperBOL: Write Project Configuration](./assets/superbol-write-project-configuration-command-prompt.png)\n\nThis will save a `superbol.toml` file at the root of each currently\nopened project directory.  Such a file will not store any\nuser-specific settings, so you can now safely put them under source\ncontrol.  Extensions dedicated to the edition of TOML files, such as\n[`tamasfe.even-better-toml`](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml),\nprovide the same level of assistance as when you edit\n`.vscode/settings.json`.\n\n\u003e [!TIP]\n\u003e\n\u003e Install the\n\u003e [`OCamlPro.SuperBOL-studio-pack`](https://marketplace.visualstudio.com/items?itemName=OCamlPro.SuperBOL-studio-pack)\n\u003e extension to get SuperBOL Studio OSS and `tamasfe.even-better-toml`\n\u003e altogether.\n\n![Editing `superbol.toml`](./assets/superbol-editing-superbol.toml.png)\n\n### Further documentation\n\nYou can check further the documentation on using the extension on\n[this page](https://ocamlpro.github.io/superbol-studio-oss/sphinx).\n\n### Mode for GNU/Emacs\n\nYou can find [here](./emacs) a mode that allows you to use the\nSuperBOL LSP server with GNU/Emacs.\n\n### Using the SuperBOL LSP server with other editors\n\n[This\npage](https://github.com/OCamlPro/superbol-studio-oss/wiki/SuperBOL-LSP)\ndocuments how to use our LSP server functionnality with other editors.\n\n### Building from sources\n\nIf you build from a clone of the git repository, make sure to update submodules:\n```bash\ngit submodule update --init --recursive\n```\n\nYou first need to install a few external dependencies to build the LSP\nserver and the VSCode extension from sources.\n\n1. First, you need to install and initialize\n   [opam](https://opam.ocaml.org/);\n\n2. Then you need a recent version[^drom-version] of our build tool\n   [drom](https://ocamlpro.github.io/drom/).  The\n   easiest way to have it running is via the following command:\n\n   ```bash\n   opam pin add https://github.com/OCamlPro/drom.git\n   ```\n\n   [^drom-version]: Current version is 0.9.2~dev3 (commit 63a5770).\n\n3. Install [node.js](https://nodejs.org/) (version \u003e=5.2.0) if it\n   is not already installed.\n\n4. You can then install all remaining dependencies, and compile the\n   LSP server along with the VS Code extension:\n\n   ```bash\n   make build-deps vsix-release\n   ```\n\n## Resources\n\n* Website: https://ocamlpro.github.io/superbol-studio-oss\n* General Documentation: https://ocamlpro.github.io/superbol-studio-oss/sphinx\n* Sources: https://github.com/ocamlpro/superbol-studio-oss\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focamlpro%2Fsuperbol-studio-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focamlpro%2Fsuperbol-studio-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focamlpro%2Fsuperbol-studio-oss/lists"}