diff --git a/documentation/content/en/articles/freebsd-src-lsp/_index.adoc b/documentation/content/en/articles/freebsd-src-lsp/_index.adoc index 8fae374362..915c06d0e8 100644 --- a/documentation/content/en/articles/freebsd-src-lsp/_index.adoc +++ b/documentation/content/en/articles/freebsd-src-lsp/_index.adoc @@ -1,249 +1,249 @@ --- -title: Use Language Servers for Developement in the FreeBSD Src Tree +title: Use Language Servers for Development in the FreeBSD Src Tree authors: - author: Ka Ho Ng email: khng@FreeBSD.org copyright: 2021 The FreeBSD Foundation -description: Use Language Servers for developement in the FreeBSD src tree to get precise go-to-definition and completion results. +description: Use Language Servers for development in the FreeBSD src tree to get precise go-to-definition and completion results. trademarks: ["freebsd"] tags: ["FreeBSD", "Language Server", "LSP"] --- = Use Language Servers for Development in the FreeBSD Src Tree :doctype: article :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: toc::[] [[intro]] == Introduction This guide is about setting up a FreeBSD src tree with language servers performing source code indexing. [[ports-required]] == Required Ports Some ports are required throughout the guide. Choose a favorite combination of tools from each category below: * Language server implementations ** package:devel/ccls[] ** package:devel/llvm12[] (Other versions are okay, but newer is better. Replace `clangd12` with clangdN in case other versions are used.) * Editors ** package:editors/vim[] ** package:editors/neovim[] ** package:editors/vscode[] * Compilation database generator ** package:devel/python[] (For llvm's scan-build-py implementation) ** package:devel/py-pip[] (For rizsotto's scan-build implementation) ** package:devel/bear[] [[editor-settings]] == Editor settings [[settings-vim]] === Vim/Neovim ==== LSP client plugins 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]. To set up the LSP client plugin for Neovim: [source,shell] .... # mkdir -p ~/.config/nvim/pack/lsp/start # git clone https://github.com/prabirshrestha/vim-lsp ~/.config/nvim/pack/lsp/start/vim-lsp .... and for Vim: [source,shell] .... # mkdir -p ~/.vim/pack/lsp/start # git clone https://github.com/prabirshrestha/vim-lsp ~/.vim/pack/lsp/start/vim-lsp .... 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: .For ccls [source,vim] .... au User lsp_setup call lsp#register_server({ \ 'name': 'ccls', \ 'cmd': {server_info->['ccls']}, \ 'allowlist': ['c', 'cpp', 'objc'], \ 'initialization_options': { \ 'cache': { \ 'hierarchicalPath': v:true \ } \ }}) .... .For clangd [source,vim] .... au User lsp_setup call lsp#register_server({ \ 'name': 'clangd', \ 'cmd': {server_info->['clangd12', '--background-index', '--header-insertion=never']}, \ 'allowlist': ['c', 'cpp', 'objc'], \ 'initialization_options': {}, \ }) .... 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/[]. 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: [source,vim] .... function! s:on_lsp_buffer_enabled() abort setlocal omnifunc=lsp#complete setlocal completeopt-=preview setlocal keywordprg=:LspHover nmap (lsp-definition) nmap ] (lsp-peek-definition) nmap (lsp-peek-definition) nmap gr (lsp-references) nmap (lsp-next-reference) nmap (lsp-previous-reference) nmap gI (lsp-implementation) nmap go (lsp-document-symbol) nmap gS (lsp-workspace-symbol) nmap ga (lsp-code-action) nmap gR (lsp-rename) nmap gm (lsp-signature-help) endfunction augroup lsp_install au! autocmd User lsp_buffer_enabled call s:on_lsp_buffer_enabled() augroup END .... [[settings-vscode]] === VSCode ==== LSP client plugins 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. 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#: .For clangd [source,json] .... [ /* Begin of your existing configurations */ ... /* End of your existing configurations */ "clangd.arguments": [ "--background-index", "--header-insertion=never" ], "clangd.path": "clangd12" ] .... .For ccls [source,json] .... [ /* Begin of your existing configurations */ ... /* End of your existing configurations */ "ccls.cache.hierarchicalPath": true ] .... [[cdb]] == Compilation database 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]#compiler_commands.json#. The database is used by language server implementations for indexing purpose. Please refer to link:https://clang.llvm.org/docs/JSONCompilationDatabase.html#format[] for details on the format of the compilation database file. [[cdb-generators]] === Generators [[generators-scan-build-py]] ==== Using scan-build-py ===== Installation `intercept-build` tool from scan-build-py is used to generate compilation database. Install package:devel/python[] to get python interpreter first. To get `intercept-build` from LLVM: [source,shell] .... # git clone https://github.com/llvm/llvm-project /path/to/llvm-project .... where [.filename]#/path/to/llvm-project/# is your desired path for the repository. Make an alias in the shell configuration file for convenience: [source,shell] .... alias intercept-build='/path/to/llvm-project/clang/tools/scan-build-py/bin/intercept-build' .... 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. ===== Usage In the top-level directory of the FreeBSD src tree, generate the compilation database with `intercept-build`: [source,shell] .... # intercept-build --append make buildworld buildkernel -j`sysctl -n hw.ncpu` .... 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]#compiler_commands.json#. [[generators-bear]] ==== Using devel/bear ===== Usage In the top-level directory of the FreeBSD src tree, to generate compilation database with `bear`: [source,shell] .... # bear -a make buildworld buildkernel -j`sysctl -n hw.ncpu` .... The `-a` flag tells `bear` to read an existing compilation database if it is present, and append the results to the database. Entries with duplicated command key are merged. The generated compilation database by default is saved in the current working directory as [.filename]#compiler_commands.json#. [[final]] == Final 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`. diff --git a/website/content/en/docs/books.adoc b/website/content/en/docs/books.adoc index 8c00ec1360..e32e7e1260 100644 --- a/website/content/en/docs/books.adoc +++ b/website/content/en/docs/books.adoc @@ -1,165 +1,165 @@ --- title: "Books and Articles Online" sidenav: docs --- include::shared/en/urls.adoc[] = Books and Articles Online == On this site All the documentation on this site can be downloaded in a variety of different formats (HTML, Postscript, PDF, and more) and compression schemes (BZip2, Zip) from the https://download.FreeBSD.org/ftp/doc/[FreeBSD Download site]. Archived copies of the FreeBSD documentation (articles, books, and textinfo manuals) are also available online at http://docs.FreeBSD.org/doc/. This documentation is provided and maintained by the link:https://www.FreeBSD.org/docproj[FreeBSD Documentation Project], and we are always looking for people to contribute new documentation and maintain existing documentation. Papers, presentations, and videos about FreeBSD are archived and catalogued on the https://papers.freebsd.org/[FreeBSD Papers] website. === Books link:{dev-model}[A project model for the FreeBSD project] (dev-model) + A formal study of the organization of the FreeBSD project. link:{faq}[The FreeBSD FAQ] (faq) + Frequently Asked Questions, and answers, covering all aspects of FreeBSD. link:{handbook}[The FreeBSD Handbook] (handbook) + A constantly evolving, comprehensive resource for FreeBSD users. link:{developers-handbook}[The FreeBSD Developers' Handbook] (developers-handbook) + For people who want to develop software for FreeBSD (and not just people who are developing FreeBSD itself). link:{arch-handbook}[The FreeBSD Architecture Handbook] (arch-handbook) + For FreeBSD system developers. This book covers the architectural details of many important FreeBSD kernel subsystems. link:{porters-handbook}[The Porter's Handbook] (porters-handbook) + Essential reading if you plan on providing a port of a third party piece of software. link:{design-44bsd}[Chapter 2 of 'The Design and Implementation of the 4.4BSD Operating System'] (design-44bsd) + Donated by Addison-Wesley, provides a design overview of 4.4BSD, from which FreeBSD was originally derived. link:{fdp-primer}[The FreeBSD Documentation Project Primer for New Contributors] (fdp-primer) + Everything you need to know in order to start contributing to the FreeBSD Documentation Project. [[ARTICLES]] === Articles link:{bsdl-gpl}[Why you should use a BSD style license for your Open Source Project] (bsdl-gpl) + Describes the benefits of releasing code under a BSD license. link:{building-products}[Building Products with FreeBSD] (building-products) + How FreeBSD can help you build a better product. link:{committers-guide}[The Committer's Guide] (committers-guide) + Introductory information for FreeBSD committers. link:{contributing}[Contributing to FreeBSD] (contributing) + How to contribute to the FreeBSD Project. link:{contributors}[The List of FreeBSD Contributors] (contributors) + A list of organizations and individuals who have helped enhance FreeBSD. link:{cups}[CUPS on FreeBSD] (cups) + How to setup CUPS with FreeBSD. link:{explaining-bsd}[Explaining BSD] (explaining-bsd) + An answer to the question "What is BSD?" link:{filtering-bridges}[Filtering Bridges] (filtering-bridges) + Configuring firewalls and filtering on FreeBSD hosts acting as bridges rather than routers. link:{fonts}[Fonts and FreeBSD] (fonts) + A description of the various font technologies in FreeBSD, and how to use them with different programs. link:{freebsd-questions}[How to get the best results from the FreeBSD-questions mailing list] (freebsd-questions) + Tips and tricks to help you maximize the chances of getting useful information from the -questions mailing list. link:{freebsd-update-server}[Build Your Own FreeBSD Update Server] (freebsd-update-server) + Using a FreeBSD Update server allows a system administrator to perform fast updates for a number of machines from a local mirror. link:{geom-class}[Writing a GEOM Class] (geom-class) + A guide to GEOM internals, and writing your own class. link:{gjournal-desktop}[Implementing UFS journaling on a desktop PC] (gjournal-desktop) + A guide to create UFS partitions configured with journaling for desktop use. link:{hubs}[Mirroring FreeBSD] (hubs) + The all in one guide for mirroring the FreeBSD website, FTP servers, and more. link:{ipsec-must}[Independent Verification of IPsec Functionality in FreeBSD] (ipsec-must) + A method for experimentally verifying IPsec functionality. link:{ldap-auth}[LDAP Authentication] (ldap-auth) + A practical guide about setting up an LDAP server on FreeBSD and how to use it for authenticating users. link:{leap-seconds}[FreeBSD Support for Leap Seconds] (leap-seconds) + A short description of how leap seconds are handled on FreeBSD. link:{linux-emulation}[Linux emulation in FreeBSD] (linux-emulation) + A technical description about the internals of the Linux emulation layer in FreeBSD. link:{linux-users}[FreeBSD Quickstart Guide for Linux Users] (linux-users) + An introductionary guide for the users that came from Linux. link:{mailing-list-faq}[Frequently Asked Questions About The FreeBSD Mailing Lists] (mailing-list-faq) + How to best use the mailing lists, such as how to help avoid frequently-repeated discussions. link:{nanobsd}[Introduction to NanoBSD] (nanobsd) + Information about the NanoBSD tools, which can be used to create FreeBSD system images for embedded applications, suitable for use on a Compact Flash card (or other mass storage medium). link:{new-users}[FreeBSD First Steps] (new-users) + For people coming to FreeBSD and &unix; for the first time. link:{pam}[Pluggable Authentication Modules] (pam) + A guide to the PAM system and modules under FreeBSD. link:{pgpkeys}[OpenPGP Keys] (pgpkeys) + All of the OpenPGP keys for FreeBSD. link:{port-mentor-guidelines}[Port Mentor Guidelines] (port-mentor-guidelines) + Guidelines for new and/or potential port mentors and mentees. link:{pr-guidelines}[FreeBSD Problem Report Handling Guidelines] (pr-guidelines) + Recommended practices for handling FreeBSD problem reports. link:{problem-reports}[Writing FreeBSD Problem Reports] (problem-reports) + How to best formulate and submit a problem report to the FreeBSD Project. link:{rc-scripting}[Practical rc.d scripting in BSD] (rc-scripting) + A guide to writing new rc.d scripts and understanding those already written. link:{freebsd-releng}[FreeBSD Release Engineering] (freebsd-releng) + Describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization. link:{releng}[Legacy FreeBSD Release Engineering] (releng) + This paper describes the approach used by past the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. link:{remote-install}[Remote Installation of the FreeBSD Operating System without a Remote Console] (remote-install) + Describes the remote installation of the FreeBSD operating system when the console of the remote system is unavailable. link:{serial-uart}[Serial and UART devices] (serial-uart) + Detailed information about the use of serial ports on FreeBSD, including several multi-port serial cards. link:{solid-state}[FreeBSD and Solid State Devices] (solid-state) + The use of solid state disk devices in FreeBSD. link:{vinum}[The vinum Volume Manager] (vinum) + Using gvinum to create RAID arrays. link:{vm-design}[Design elements of the FreeBSD VM system] (vm-design) + An easy to follow description of the design of the FreeBSD virtual memory system. -link:{freebsd-src-lsp}[Use Language Servers for Developement in the FreeBSD Src Tree] (freebsd-src-lsp) + +link:{freebsd-src-lsp}[Use Language Servers for Development in the FreeBSD Src Tree] (freebsd-src-lsp) + A guide about setting up a FreeBSD src tree with language servers performing source code indexing. == Articles on other web sites Various independent efforts have also produced a great deal of useful information about FreeBSD. * Niels Jorgensen has authored an academic study on the dynamics of the FreeBSD development process: http://www.ruc.dk/~nielsj/research/publications/freebsd.pdf["Putting it All in the Trunk, Incremental Software Development in the FreeBSD Open Source Project"] [Information Systems Journal (2001) 11, 321-336]. * mailto:mckusick@mckusick.com[Kirk McKusick], one of the original architects of BSD at U.C. Berkeley, teaches two http://www.mckusick.com/courses/[4.4BSD Kernel Internals] courses using FreeBSD. For those unable to attend the courses in person, a video tape series is also now available. * http://software.intel.com/sites/default/files/profiling_debugging_freebsd_kernel_321772.pdf[Profiling and Debugging the FreeBSD Kernel] * http://software.intel.com/sites/default/files/debugging_buffer_overruns_322486.pdf[Debugging Buffer Overruns in the FreeBSD Kernel] * Appendix A from the college textbook _Operating Systems Concepts_ by Silberschatz, Galvin and Gagne has been made available online in http://www.wiley.com/college/silberschatz6e/0471417432/pdf/bsd.pdf[PDF format]. The appendix is dedicated to FreeBSD and offers a good introduction to FreeBSD's internals.