diff --git a/docs/getting_started.org b/docs/getting_started.org index d65db0fb8..fb89af6d5 100644 --- a/docs/getting_started.org +++ b/docs/getting_started.org @@ -63,15 +63,12 @@ - [[#a-backtrace-from-bindoom][A backtrace from `bin/doom`]] - [[#evaluating-elisp-on-the-fly][Evaluating Elisp on-the-fly]] - [[#how-to-determine-the-origin-of-a-bug][How to determine the origin of a bug]] - - [[#acquiring-a-backtrace][Acquiring a backtrace]] - - [[#enabling-debug-on-error-1][Enabling ~debug-on-error~]] - - [[#a-backtrace-from-bindoom-1][A backtrace from ~bin/doom~]] - - [[#use-the-sandbox][Use the sandbox]] - - [[#opening-the-sandbox][Opening the sandbox]] - - [[#launching-the-sandbox][Launching the sandbox]] - - [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]] - - [[#bisecting-your-private-config][Bisecting your private config]] - - [[#bisecting-doom-emacs][Bisecting Doom Emacs]] + - [[#testing-in-dooms-sandbox][Testing in Doom's sandbox]] + - [[#opening-the-sandbox][Opening the sandbox]] + - [[#launching-the-sandbox][Launching the sandbox]] + - [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]] + - [[#bisecting-your-private-config][Bisecting your private config]] + - [[#bisecting-doom-emacs][Bisecting Doom Emacs]] * Install To embark on this grand Emacs adventure, you'll need a couple things installed, @@ -1122,39 +1119,7 @@ are couple things you can do: (=gR=) to evaluate code, ** How to determine the origin of a bug -*** Acquiring a backtrace -If you encounter an error while using Doom Emacs, you're probably about to head -off and file a bug report (or request help on [[https://discord.gg/bcZ6P3y][our Discord server]]. Before you do, -please generate a backtrace to include with it. - -To do so you must enable ~debug-on-error~, then recreate the error. - -**** Enabling ~debug-on-error~ -There are three ways to enable `debug-on-error`: - -1. Start Emacs with ~emacs --debug-init~. Use this for errors that occur at - startup. -2. Evil users can press =SPC h d d= and non-evil users can press =C-h d d=. -3. If the above don't work, there's always: ~M-x toggle-debug-on-error~ - -Now that ~debug-on-error~ is on, recreate the error. A window should pop up with -a backtrace. - -**** A backtrace from ~bin/doom~ - -To acquire a backtrace from an error emitted from `bin/doom`, re-run the same -command with the ~-d~ / ~--debug~ switches or the `DEBUG` environment variable: - -#+BEGIN_SRC sh -doom -d refresh -doom --debug install -DEBUG=1 doom update -#+END_SRC - -*Note:* switch order is important. ~-d~ / ~--debug~ /must/ come right after -~doom~. - -*** Use the sandbox +** Testing in Doom's sandbox "The sandbox" is one of Doom Emacs' features; it is a test bed for running elisp in a fresh instance of Emacs with varying amounts of Doom loaded (none at all, all of it, or somewhere in between). This can be helpful for isolating bugs to @@ -1166,7 +1131,7 @@ developers of the relevant plugins or, perhaps, the Emacs devs themselves. Otherwise, it is best to bring it up on the Doom Emacs issue list, rather than confusing and inundating the Emacs community with Doom-specific issues. -**** Opening the sandbox +*** Opening the sandbox There are three common ways to access the sandbox: + =SPC h E= (for evil users) @@ -1177,7 +1142,7 @@ Doing any of the above will pop up a ~*doom:sandbox*~ window. What you enter into this buffer will be executed in the new instance of Emacs when you decide to launch it. -**** Launching the sandbox +*** Launching the sandbox You have four options when it comes to launching the sandbox: - =C-c C-c= :: This launches "vanilla Emacs". Vanilla means nothing is loaded; @@ -1197,7 +1162,7 @@ You have four options when it comes to launching the sandbox: All new instances will inherit your ~load-path~ so you can access any packages you have installed. #+END_QUOTE -**** Testing packages in the sandbox +*** Testing packages in the sandbox Instances of Emacs launched from the sandbox have inherited your ~load-path~. This means you can load packages -- even in Vanilla Emacs -- without worrying about installing or setting them up. Just ~(require PACKAGE)~ and launch the @@ -1209,5 +1174,5 @@ sandbox. e.g. (call-interactively #'magit-status) #+END_SRC -*** Bisecting your private config -*** Bisecting Doom Emacs +** TODO Bisecting your private config +** TODO Bisecting Doom Emacs