From 6ca84e19b63c375acdd2c066b59c50abe02d8574 Mon Sep 17 00:00:00 2001 From: Excalamus Date: Sat, 14 Nov 2020 22:28:49 -0500 Subject: [PATCH 1/3] Add basic installation to README --- README.org | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.org b/README.org index 50f49b3c..68b3fd9e 100644 --- a/README.org +++ b/README.org @@ -8,6 +8,7 @@ - [[#dap-mode][dap-mode]] - [[#summary][Summary]] - [[#project-status][Project status]] + - [[#Install][Install]] - [[#usage][Usage]] - [[#features][Features]] - [[#configuration][Configuration]] @@ -23,6 +24,37 @@ *** Project status The API considered unstable until 1.0 release is out. It is tested against Java, Python, Ruby, Elixir and LLDB (C/C++/Objective-C/Swift). +** Install + There are several ways to install ~dap-mode~. +*** ~package.el~ + To use the native Emacs package manager, ~package.el~, first add + [[https://melpa.org][MELPA]] or [[https://stable.melpa.org/][MELPA Stable]] to the ~package-archive~ alist: + + #+begin_src elisp + (require 'package) + (add-to-list 'package-archives + '("melpa-stable" . "https://stable.melpa.org/packages/")) + #+end_src + + Next, + - ~M-x package-refresh-contents~ to refresh the package listing + - ~M-x package-install RET dap-mode RET~ to install ~dap-mode~ + + Finally, load Emacs Lisp packages and enable ~dap-mode~: + + #+begin_src elisp + (package-initialize) + (dap-mode 1) + #+end_src +*** [[https://github.com/jwiegley/use-package][~use-package.el~]] + For users of ~use-package~, install and enable ~dap-mode~ with: + + #+begin_src elisp + (use-package dap-mode + :ensure t + :init + (dap-mode 1)) + #+end_src ** Usage The main entry points are ~dap-debug~ and ~dap-debug-edit-template~. The first one asks for a registered debug template and starts the configuration using From 031f0b96541f9604124ccddbcfd8b90db597deca Mon Sep 17 00:00:00 2001 From: Excalamus Date: Sat, 14 Nov 2020 22:29:47 -0500 Subject: [PATCH 2/3] Link configuration page to install Provide users a reference to package installation page in case they land here first. Explain difference between `dap-mode` installation and the need to install an external debugger. --- docs/page/configuration.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/page/configuration.md b/docs/page/configuration.md index 09113ad1..280fa31b 100644 --- a/docs/page/configuration.md +++ b/docs/page/configuration.md @@ -1,9 +1,16 @@ Configuration =============== +After [installing +`dap-mode`](https://github.com/emacs-lsp/dap-mode#Install), you may +need to install a DAP compliant debugger. `dap-mode` will need to be +configured to connect with it. This most easily done with +`dap-auto-configure-mode`. + ## DAP mode configuration -For an auto-configuration enable the `dap-auto-configure-mode`. You can configure which features from `dap-mode` do you want with `dap-auto-configure-features`: + +You can configure which features from `dap-mode` do you want with `dap-auto-configure-features`: ```elisp ;; Enabling only some features From 392b0b16f1290018707126194a433ed94b885c45 Mon Sep 17 00:00:00 2001 From: Excalamus Date: Sat, 14 Nov 2020 22:33:03 -0500 Subject: [PATCH 3/3] Update Python config with debugpy instructions Remove outdated ptvsd instructions and flesh out explanation. See #401. --- docs/page/configuration.md | 43 ++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/docs/page/configuration.md b/docs/page/configuration.md index 280fa31b..b64aecf0 100644 --- a/docs/page/configuration.md +++ b/docs/page/configuration.md @@ -84,26 +84,40 @@ settings. 1. Installation - - install latest version of ptvsd. + A Python DAP compliant debugger is provided by `debugpy`. This + can be installed with: - ``` bash - pip install "ptvsd>=4.2" - ``` + ``` bash + pip install "debugpy" + ``` - - Then add the following line in your config: + Use the following to load Python configurations into `dap-debug`: - ``` elisp - (require 'dap-python) - ``` + ``` elisp + (require 'dap-python) + ``` - This will add the python related configuration to `dap-debug`. + Use `dap-python-debugger` to specify which debugger to use. + + For example, + + ``` elisp + (use-package dap-mode + :config + (require 'dap-python) + (setq dap-python-debugger 'debugpy)) + ``` 2. Usage - A template named "Python :: Run Configuration" will appear, which - will execute the currently visited module. This will fall short - whenever you need to specify arguments, environment variables or - execute a setuptools based script. In such case, define a template: + If using a virtual environment, make sure it is activated. Next, + call `dap-auto-configure-mode`. Use `dap-debug` when you are + ready to debug. You are able to choose from various Run + Configurations (e.g. `Python :: Run file (buffer)`) which specify + debug parameters. Press `` to see available templates. + + You can specify arguments, environment variables or execute a + setuptools based script, with a custom template: ``` elisp (dap-register-debug-template "My App" @@ -116,6 +130,9 @@ settings. :name "My App")) ``` + Templates can be quickly created and modified using + `dap-debug-edit-template`. + ## Ruby - Download and extract [VSCode Ruby