Path: blob/main/documentation/content/en/articles/freebsd-src-lsp/_index.po
18096 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2024-01-17 20:35-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:1 #, no-wrap msgid "Use Language Servers for development in the FreeBSD src tree to get precise go-to-definition and completion results." msgstr "" #. type: Title = #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:1 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:13 #, no-wrap msgid "Use Language Servers for Development in the FreeBSD Src Tree" msgstr "" #. type: Title == #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:47 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:50 msgid "" "This guide is about setting up a FreeBSD src tree with language servers " "performing source code indexing. The guide describes the steps for Vim/" "NeoVim and VSCode. If you use a different text editor you can use this guide " "as a reference and search the equivalent commands for your preferred editor." msgstr "" #. type: Title == #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:52 #, no-wrap msgid "Requirements" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:55 msgid "" "In order to follow this guide we need to install certain requirements. We " "need a Language server, `ccls` or `clangd`, and optionally a compilation " "database." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:57 msgid "" "The installation of the Language server can be performed via `pkg` or via " "ports. If we chose `clangd` we need to install `llvm`." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:59 msgid "Using `pkg` to install `ccls`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:63 #, no-wrap msgid "# pkg install ccls\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:66 msgid "" "If we want to use `clangd` we need to install `llvm` (The example command " "uses `llvm15` but choose the version you desire):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:70 #, no-wrap msgid "# pkg install llvm15\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:73 msgid "" "To install via ports choose a favorite combination of tools from each " "category below:" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:75 msgid "Language server implementations" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:76 msgid "package:devel/ccls[]" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:77 msgid "" "package:devel/llvm12[] (Other versions are okay, but newer is better. " "Replace `clangd12` with clangdN in case other versions are used.)" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:78 msgid "Editors" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:79 msgid "package:editors/vim[]" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:80 msgid "package:editors/neovim[]" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:81 msgid "package:editors/vscode[]" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:82 msgid "Compilation database generator" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:83 msgid "package:devel/python[] (For llvm's scan-build-py implementation)" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:84 msgid "package:devel/py-pip[] (For rizsotto's scan-build implementation)" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:85 msgid "package:devel/bear[]" msgstr "" #. type: Title == #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:87 #, no-wrap msgid "Editor settings" msgstr "" #. type: Title === #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:90 #, no-wrap msgid "Vim/Neovim" msgstr "" #. type: Title ==== #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:92 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:178 #, no-wrap msgid "LSP client plugins" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:96 msgid "" "The built-in plugin manager is used for both editors in this example. The " "LSP client plugin used is link:https://github.com/prabirshrestha/vim-" "lsp[prabirshrestha/vim-lsp]." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:98 msgid "To set up the LSP client plugin for Neovim:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:103 #, no-wrap msgid "" "# mkdir -p ~/.config/nvim/pack/lsp/start\n" "# git clone https://github.com/prabirshrestha/vim-lsp ~/.config/nvim/pack/lsp/start/vim-lsp\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:106 msgid "and for Vim:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:111 #, no-wrap msgid "" "# mkdir -p ~/.vim/pack/lsp/start\n" "# git clone https://github.com/prabirshrestha/vim-lsp ~/.vim/pack/lsp/start/vim-lsp\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:114 msgid "" "To enable the LSP client plugin in the editor, add the following snippet " "into [.filepath]#~/.config/nvim/init.vim# when using Neovim, or [." "filepath]#~/.vim/vimrc# when using Vim:" msgstr "" #. type: Block title #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:115 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:203 #, no-wrap msgid "For ccls" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:127 #, no-wrap msgid "" "au User lsp_setup call lsp#register_server({\n" " \\ 'name': 'ccls',\n" " \\ 'cmd': {server_info->['ccls']},\n" " \\ 'allowlist': ['c', 'cpp', 'objc'],\n" " \\ 'initialization_options': {\n" " \\ 'cache': {\n" " \\ 'hierarchicalPath': v:true\n" " \\ }\n" " \\ }})\n" msgstr "" #. type: Block title #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:129 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:188 #, no-wrap msgid "For clangd" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:138 #, no-wrap msgid "" "au User lsp_setup call lsp#register_server({\n" " \\ 'name': 'clangd',\n" " \\ 'cmd': {server_info->['clangd15', '--background-index', '--header-insertion=never']},\n" " \\ 'allowlist': ['c', 'cpp', 'objc'],\n" " \\ 'initialization_options': {},\n" " \\ })\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:141 msgid "" "Depending on the version that you installed for `clangd` you might need to " "update the `server-info` to point to the correct binary." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:144 msgid "" "Please refer to link:https://github.com/prabirshrestha/vim-lsp/blob/master/" "README.md#registering-servers[] to learn about setting up key bindings and " "code completion. The official site of clangd is link:https://clangd.llvm." "org[], and the repository link of ccls is link:https://github.com/MaskRay/" "ccls/[]." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:147 msgid "" "Below are the reference settings of keybindings and code completions. Put " "the following snippet into [.filepath]#~/.config/nvim/init.vim#, or [." "filepath]#~/.vim/vimrc# for Vim users to use it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:154 #, no-wrap msgid "" "function! s:on_lsp_buffer_enabled() abort\n" " setlocal omnifunc=lsp#complete\n" " setlocal completeopt-=preview\n" " setlocal keywordprg=:LspHover\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:168 #, no-wrap msgid "" " nmap <buffer> <C-]> <plug>(lsp-definition)\n" " nmap <buffer> <C-W>] <plug>(lsp-peek-definition)\n" " nmap <buffer> <C-W><C-]> <plug>(lsp-peek-definition)\n" " nmap <buffer> gr <plug>(lsp-references)\n" " nmap <buffer> <C-n> <plug>(lsp-next-reference)\n" " nmap <buffer> <C-p> <plug>(lsp-previous-reference)\n" " nmap <buffer> gI <plug>(lsp-implementation)\n" " nmap <buffer> go <plug>(lsp-document-symbol)\n" " nmap <buffer> gS <plug>(lsp-workspace-symbol)\n" " nmap <buffer> ga <plug>(lsp-code-action)\n" " nmap <buffer> gR <plug>(lsp-rename)\n" " nmap <buffer> gm <plug>(lsp-signature-help)\n" "endfunction\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:173 #, no-wrap msgid "" "augroup lsp_install\n" " au!\n" " autocmd User lsp_buffer_enabled call s:on_lsp_buffer_enabled()\n" "augroup END\n" msgstr "" #. type: Title === #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:176 #, no-wrap msgid "VSCode" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:183 msgid "" "LSP client plugins are required to launch the language server daemon. Press " "`Ctrl+Shift+X` to show the extension online search panel. Enter `llvm-vs-" "code-extensions.vscode-clangd` when running clangd, or `ccls-project.ccls` " "when running ccls." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:187 msgid "" "Then, press `Ctrl+Shift+P` to show the editor commands palette. Enter " "`Preferences: Open Settings (JSON)` into the palette and hit `Enter` to open " "[.filepath]#settings.json#. Depending on the language server " "implementations, put one of the following JSON key/value pairs in [." "filepath]#settings.json#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:201 #, no-wrap msgid "" "[\n" " /* Begin of your existing configurations */\n" " ...\n" " /* End of your existing configurations */\n" " \"clangd.arguments\": [\n" " \"--background-index\",\n" " \"--header-insertion=never\"\n" " ],\n" " \"clangd.path\": \"clangd12\"\n" "]\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:212 #, no-wrap msgid "" "[\n" " /* Begin of your existing configurations */\n" " ...\n" " /* End of your existing configurations */\n" " \"ccls.cache.hierarchicalPath\": true\n" "]\n" msgstr "" #. type: Title == #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:215 #, no-wrap msgid "Compilation database" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:221 msgid "" "A Compilation database contains an array of compile command objects. Each " "object specifies a way of compiling a source file. The compilation database " "file is usually [.filename]#compile_commands.json#. The database is used by " "language server implementations for indexing purpose." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:223 msgid "" "Please refer to link:https://clang.llvm.org/docs/JSONCompilationDatabase." "html#format[] for details on the format of the compilation database file." msgstr "" #. type: Title === #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:225 #, no-wrap msgid "Generators" msgstr "" #. type: Title ==== #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:228 #, no-wrap msgid "Using scan-build-py" msgstr "" #. type: Title ===== #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:230 #, no-wrap msgid "Installation" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:234 msgid "" "`intercept-build` tool from scan-build-py is used to generate compilation " "database." msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:237 msgid "" "Install package:devel/python[] to get python interpreter first. To get " "`intercept-build` from LLVM:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:241 #, no-wrap msgid "# git clone https://github.com/llvm/llvm-project /path/to/llvm-project\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:244 msgid "" "where [.filename]#/path/to/llvm-project/# is your desired path for the " "repository. Make an alias in the shell configuration file for convenience:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:248 #, no-wrap msgid "alias intercept-build='/path/to/llvm-project/clang/tools/scan-build-py/bin/intercept-build'\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:254 msgid "" "link:https://github.com/rizsotto/scan-build[rizsotto/scan-build] can be used " "instead of LLVM's scan-build-py. The LLVM's scan-build-py was rizsotto/scan-" "build merged into the LLVM tree. This implementation can be installed by " "`pip install --user scan-build`. The `intercept-build` script is in [." "filename]#~/.local/bin# by default." msgstr "" #. type: Title ===== #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:255 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:271 #, no-wrap msgid "Usage" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:258 msgid "" "In the top-level directory of the FreeBSD src tree, generate the compilation " "database with `intercept-build`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:262 #, no-wrap msgid "# intercept-build --append make buildworld buildkernel -j`sysctl -n hw.ncpu`\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:267 msgid "" "The `--append` flag tells the `intercept-build` to read an existing " "compilation database (if a compilation database exists) and append the " "results to the database. Entries with duplicated command keys are merged. " "The generated compilation database by default is saved in the current " "working directory as [.filename]#compile_commands.json#." msgstr "" #. type: Title ==== #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:269 #, no-wrap msgid "Using devel/bear" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:274 msgid "" "In the top-level directory of the FreeBSD src tree, to generate compilation " "database with `bear`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:278 #, no-wrap msgid "# bear --append -- make buildworld buildkernel -j`sysctl -n hw.ncpu`\n" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:283 msgid "" "The `--append` flag tells `bear` to read an existing compilation database if " "it is present, and append the results to the database. Entries with " "duplicated command keys are merged. The generated compilation database by " "default is saved in the current working directory as [." "filename]#compile_commands.json#." msgstr "" #. type: Title == #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:285 #, no-wrap msgid "Final" msgstr "" #. type: Plain text #: documentation/content/en/articles/freebsd-src-lsp/_index.adoc:289 msgid "" "Once the compilation database is generated, open any source files in the " "FreeBSD src tree and LSP server daemon will be launched as well in " "background. Opening source files in the src tree for the first time takes " "significantly longer time before the LSP server is able to give a complete " "result, due to initial background indexing by the LSP server compiling all " "the listed entries in the compilation database. The language server daemon " "however does not index the source files not appearing in the compilation " "database, thus no complete results are shown on source files not being " "compiled during the `make`." msgstr ""