(docs)readme: update installation section (#1787)

2025-08-01 12:17:21 -05:00 · 2021-08-19 17:05:18 +03:00
parent d4cbb1d499
commit 887c49c89c
1 changed files with 153 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -33,38 +33,170 @@ solution for anyone already using Org-mode for their personal wiki.

 ## Installation

-You can install `org-roam` using `package.el`:
+Down below you will find basic installation instructions for how to quickly
+install `org-roam` using various environments for various purposes. For more
+detailed information, please read the [manual][docs].
+
+### Using `package.el`
+<details>
+<summary>Toggle instuctions</summary>
+
+You can install `org-roam` from [MELPA](https://melpa.org/) or [MELPA
+Stable](https://stable.melpa.org/) using `package.el`:

 ```
 M-x package-install RET org-roam RET
 ```

-Here's a sample configuration with `use-package`:
+Here's a very basic sample for configuration of `org-roam` using `use-package`:

 ```emacs-lisp
 (use-package org-roam
-      :ensure t
-      :custom
-      (org-roam-directory (file-truename "/path/to/org-files/"))
-      :bind (("C-c n l" . org-roam-buffer-toggle)
-             ("C-c n f" . org-roam-node-find)
-             ("C-c n g" . org-roam-graph)
-             ("C-c n i" . org-roam-node-insert)
-             ("C-c n c" . org-roam-capture)
-             ;; Dailies
-             ("C-c n j" . org-roam-dailies-capture-today))
-      :config
-      (org-roam-db-autosync-mode)
-      ;; If using org-roam-protocol
-      (require 'org-roam-protocol))
+  :ensure t
+  :custom
+  (org-roam-directory (file-truename "/path/to/org-files/"))
+  :bind (("C-c n l" . org-roam-buffer-toggle)
+         ("C-c n f" . org-roam-node-find)
+         ("C-c n g" . org-roam-graph)
+         ("C-c n i" . org-roam-node-insert)
+         ("C-c n c" . org-roam-capture)
+         ;; Dailies
+         ("C-c n j" . org-roam-dailies-capture-today))
+  :config
+  (org-roam-db-autosync-mode)
+  ;; If using org-roam-protocol
+  (require 'org-roam-protocol))
 ```

-The `file-truename` function is only necessary when you use symbolic links
-inside `org-roam-directory`: Org-roam does not resolve symbolic links.
+Note that the `file-truename` function is only necessary when you use symbolic
+link to `org-roam-directory`. Org-roam won't automatically resolve symbolic link
+to the directory.
+</details>

-Org-roam requires sqlite to function. Org-roam optionally uses Graphviz for
-graph-related functionality. It is recommended to install PCRE-enabled ripgrep
-for better performance and extended functionality.
+### Using `straight.el`
+<details>
+<summary>Toggle instuctions</summary>
+
+Installation from MELPA or MELPA Stable using `straight.el`:
+
+```emacs-lisp
+(straight-use-package 'org-roam)
+```
+
+Or with `use-package`:
+
+```emacs-lisp
+(use-package org-roam
+  :straight t
+  ...)
+```
+
+If you need to install the package directly from the source repository, instead
+of from MELPA, the next sample shows how to do so:
+
+```emacs-lisp
+(use-package org-roam
+  :straight (:host github :repo "org-roam/org-roam"
+             :files (:defaults "extensions/*"))
+  ...)
+```
+
+If you plan to use your own local fork for the development and contribution, the
+next sample will get you there:
+
+```emacs-lisp
+(use-package org-roam
+  :straight (:local-repo "/path/to/org-roam-fork"
+             :files (:defaults "extensions/*")
+             :build (:not compile))
+  ...)
+```
+</details>
+
+### Using Doom Emacs
+<details>
+<summary>Toggle instuctions</summary>
+
+Doom's `:lang org` module comes with support for `org-roam`, but it's not
+enabled by default. To activate it pass `+roam2` flag to `org` module in your
+`$DOOMDIR/init.el` (e.g. `(org +roam2)`), save the file and run `doom sync -u`
+in your shell.
+
+To provide better stability, Doom pins the package to a specific commit. If you
+need to unpin it *(not recommended doing that, request Doom to bump the package
+instead)* use the next in your `packages.el`:
+
+```emacs-lisp
+(unpin! org-roam)
+```
+
+If for some reasons you want to use a different recipe for `org-roam`, you can
+use the next form in your `packages.el` to install the package from a recipe
+repository (e.g. MELPA):
+
+```emacs-lisp
+(package! org-roam)
+```
+
+You can pass `:pin "commit hash"` to pin the package to a specific commit.
+
+With the next sample you can install the package directly from the source
+repository:
+
+```emacs-lisp
+(package! org-roam
+  :recipe (:host github :repo "org-roam/org-roam"
+           :files (:defaults "extensions/*")))
+```
+
+And if you plan to use your own local fork for the development or contribution,
+the next sample will get you there:
+
+```emacs-lisp
+(package! org-roam
+  :recipe (:local-repo "/path/to/org-roam-fork"
+           :files (:defaults "extensions/*")
+           :build (:not compile)))
+```
+</details>
+
+### Without a package manager
+<details>
+<summary>Toggle instructions</summary>
+
+To install the package without using a package manager you have the next two
+options:
+
+1. Install the package by cloning it with `git` from the source repository.
+2. Or install the package by downloading the latest [release
+   version](https://github.com/org-roam/org-roam/releases).
+   
+In both of the cases you will need to ensure that you have all the required
+dependencies. These include:
+
+- dash
+- f
+- s
+- org (9.4 is the minimal required version!)
+- emacsql
+- emacsql-sqlite
+- magit-section
+- filenotify-recursive
+
+After installing the package, you will need to properly setup `load-path` to the
+package:
+
+``` emacs-lisp
+(add-to-list 'load-path "/path/to/org-roam/")
+(add-to-list 'load-path "/path/to-org-roam/extensions/")
+```
+
+After which you should be able to resolve `(require 'org-roam)` call without any
+problems.
+
+Org-roam also comes with `.texi` files to integrate with Emacs' built-in Info
+system. Read the manual to find more details for how to install them manually.
+</details>

 ## Getting Started