:PROPERTIES:
:ID:       a1f19097-8dee-4b18-9e86-0db6e13849cb
:END:
#+title:     :lang scad
#+subtitle:  3D CAD modelling for nerds
#+created:   November 26, 2023
#+since:     3.0.0 (#COMMIT-OR-PR-REF)

* Description :unfold:
  This module add [[https://openscad.org/][OpenSCAD]] support to Doom Emacs.

This allows you to design complex, 3D models all from the comfort of the editor you love!

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +lsp ::
  Enable LSP support for ~scad-mode~. Requires [[doom-module::tools lsp]] and a
  langserver (supports [[https://github.com/Leathong/openscad-LSP][openscad-lsp]]).

** Packages
- [[doom-package:scad-mode]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

While the module itself doesn't *technically* require OpenSCAD to be installed, if you want to actually render geometry, you should install it through your distribution's package manager.

#+begin_src shell
apt-get install openscad # Debian / Ubuntu / Kubuntu
yum install openscad # Fedora
pacman -S openscad # Arch Linux
brew install --cask openscad # MacOS
#+end_src

** LSP Server

If you'd like to have language server support, you need to install [[https://github.com/Leathong/openscad-LSP][openscad-lsp]] manually.
This currently isn't packaged by anyone, so you either need to grab a binary from the source or build it manually.

To build it, you need a [[https://www.rust-lang.org/learn/get-started][Rust toolchain]] installed, then you can run

#+begin_src shell
cargo install openscad-lsp
#+end_src

* Usage
To start, create a new =.scad= file and start writing. Once you have some renderable geometry you can render it directly in editor with ~scad-preview~.
Otherwise, you can open in OpenSCAD with ~scad-open~, where by default saves in Emacs will cause a re-render in OpenSCAD.
Once you're happy, you can render to a variety of 3D file formats from within OpenSCAD or to an STL for 3D printing with ~scad-export~.

** Keybindings

| Keybind          | Command        |
|------------------+----------------|
| [[kbd:][<localleader> e]]  | ~scad-export~  |
| [[kbd:][<localleader> o]]  | ~scad-open~    |
| [[kbd:][<localleader> p ]] | ~scad-preview~ |

* TODO Configuration
#+begin_quote
󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
    
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote