You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
191 lines
7.2 KiB
191 lines
7.2 KiB
## Basic Install and Configuration |
|
|
|
Org-roam is now available on MELPA, so you can install it via the following |
|
command: |
|
|
|
``` |
|
M-x package-install RET org-roam RET |
|
``` |
|
|
|
Alternatively, you may use package managers such as [straight][straight] or |
|
[quelpa][quelpa] to install the package. |
|
|
|
The recommended method of configuration is to use [use-package][use-package]. |
|
|
|
```emacs-lisp |
|
(use-package org-roam |
|
:hook |
|
(after-init . org-roam-mode) |
|
:custom |
|
(org-roam-directory "/path/to/org-files/") |
|
:bind (:map org-roam-mode-map |
|
(("C-c n l" . org-roam) |
|
("C-c n f" . org-roam-find-file) |
|
("C-c n b" . org-roam-switch-to-buffer) |
|
("C-c n g" . org-roam-graph-show)) |
|
:map org-mode-map |
|
(("C-c n i" . org-roam-insert)))) |
|
``` |
|
|
|
Or without `use-package`: |
|
|
|
```emacs-lisp |
|
(require 'org-roam) |
|
(define-key org-roam-mode-map (kbd "C-c n l") #'org-roam) |
|
(define-key org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file) |
|
(define-key org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer) |
|
(define-key org-roam-mode-map (kbd "C-c n g") #'org-roam-graph-show) |
|
(define-key org-mode-map (kbd "C-c n i") #'org-roam-insert) |
|
(org-roam-mode +1) |
|
``` |
|
|
|
The [Configuration](configuration.md) page details some of the common |
|
configuration options available. |
|
|
|
## Spacemacs |
|
|
|
If you are using Spacemacs, install org-roam by creating a simple layer that |
|
wraps Org-roam. Paste the following into a new file |
|
`~/.emacs.d/private/org-roam/packages.el`. |
|
|
|
```emacs-lisp |
|
(defconst org-roam-packages |
|
'((org-roam :location |
|
(recipe :fetcher github :repo "jethrokuan/org-roam")))) |
|
|
|
(defun org-roam/init-org-roam () |
|
(use-package org-roam |
|
:hook |
|
(after-init . org-roam-mode) |
|
:custom |
|
(org-roam-directory "/path/to/org-files/") |
|
:init |
|
(progn |
|
(spacemacs/declare-prefix "ar" "org-roam") |
|
(spacemacs/set-leader-keys |
|
"arl" 'org-roam |
|
"art" 'org-roam-today |
|
"arf" 'org-roam-find-file |
|
"arg" 'org-roam-graph-show) |
|
|
|
(spacemacs/declare-prefix-for-mode 'org-mode "mr" "org-roam") |
|
(spacemacs/set-leader-keys-for-major-mode 'org-mode |
|
"rl" 'org-roam |
|
"rt" 'org-roam-today |
|
"rb" 'org-roam-switch-to-buffer |
|
"rf" 'org-roam-find-file |
|
"ri" 'org-roam-insert |
|
"rg" 'org-roam-graph-show)))) |
|
``` |
|
|
|
Next, append `org-roam` to the `dotspacemacs-configuration-layers` |
|
list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or |
|
restart Emacs to load `org-roam`. It's functions are available under |
|
the prefix `SPC a r` and `, r` when visiting an org-mode buffer. |
|
|
|
If you also have the ranger layer installed, the prefix 'ar' conflict |
|
with that of the ranger layer. You might want to change it to 'aor' |
|
(also change the 'ar' to 'aor' in the other key-binding declarations) |
|
|
|
## Doom Emacs |
|
|
|
[Doom Emacs][doom] has a `+roam` flag on its `org` module for easy |
|
installation and configuration. Simply add the flag to the `org` section |
|
of your `~/.doom.d/init.el` and run `~/.emacs.d/bin/doom sync`. |
|
|
|
[use-package]: https://github.com/jwiegley/use-package |
|
[straight]: https://github.com/raxod502/straight.el |
|
[quelpa]: https://github.com/quelpa/quelpa |
|
[doom]: https://github.com/hlissner/doom-emacs |
|
[doom-getting-started]: https://github.com/hlissner/doom-emacs/blob/develop/docs/getting_started.org#configuring-packages |
|
|
|
## Windows |
|
|
|
On Windows, if you follow the installation instructions above, you will likely get the error message: **"No EmacSQL SQLite binary available, aborting"**, and `org-roam` won't start properly. |
|
|
|
You need to do some additional steps to get `org-roam` to work. |
|
|
|
Essentially, you will need to have a binary file for `emacsql-sqlite` so that your Emacs can work with `sqlite` database -- `org-roam` uses it to track backlinks. The following options have been reported to work by Windows users in the community. |
|
|
|
Option 1. **Windows Subsystem for Linux (WSL)** |
|
: This option lets you use Linux on your Windows machine. It's Linux, so you don't need to do anything specific for Windows. |
|
|
|
Option 2. **mingw-x64** |
|
: Use mingw-x64. You would spend a bit of time to download it, and get familiar with how it works. You should be able to use Linux tools within your Windows [more contribution welcome]. |
|
|
|
Option 3. **scoop** |
|
: Use [scoop](https://scoop.sh/) to install a couple of software tools (make and gcc) and manually compile a binary (`.exe`) file yourself. Find a short step-by-step guide below. |
|
|
|
Option 4. **emacsql-sqlite3** |
|
: Use another Emacs package called [`emacsql-sqlite3`](https://github.com/cireu/emacsql-sqlite3). You can download an [official binary](https://sqlite.org/download.html) for `sqlite3`. `emacsql-sqlite3` lets you use it. For this option to work, you need to adjust the `org-roam` source code, and get your modified version to work in your Emacs environment. Find a suggestion below. |
|
|
|
### scoop |
|
1. In PowerShell, install `scoop` ([instruction here](https://scoop.sh/)). |
|
|
|
```powershell |
|
iwr -useb get.scoop.sh | iex |
|
``` |
|
|
|
2. In PowerShell, install `make` and `gcc` via scoop |
|
|
|
```powershell |
|
scoop install make gcc |
|
``` |
|
|
|
3. In Emacs, install the `emacsql-sqlite` package for your Emacs if it is not done yet. |
|
|
|
4. In PowerShell, move to the directory where `emacsql.c` is stored. |
|
|
|
With MELPA, it is likely to be under your ELPA folder: |
|
|
|
``` |
|
~\AppData\Roaming\.emacs.d\elpa\emacsql-sqlite-20190727.1710\sqlite |
|
``` |
|
|
|
With Doom Emacs, it should be under your `.emacs\.local`: |
|
|
|
``` |
|
~\.emacs.d\.local\straight\build\emacsql-sqlite\sqlite |
|
``` |
|
|
|
Check the files via `dir` command. You should see these files: |
|
|
|
```powershell |
|
Mode LastWriteTime Length Name |
|
---- ------------- ------ ---- |
|
-a---- 22/03/2020 12:10 PM 5170 emacsql.c |
|
-a---- 22/03/2020 12:10 PM 439 Makefile |
|
-a---- 22/03/2020 12:10 PM 7516138 sqlite3.c |
|
-a---- 22/03/2020 12:10 PM 526684 sqlite3.h |
|
``` |
|
|
|
5. Compile the `.exe` file with `make` |
|
|
|
|
|
```powershell |
|
make emacsql-sqlite CC=gcc LDLIBS= |
|
``` |
|
|
|
You will see the process triggered with lots of text automatically scrolling down; it may take a couple of minutes for compilation to finish. |
|
|
|
Once compilation is done, check that `emacsql-sqlite.exe` has been added to the directory. |
|
|
|
6. Relaunch Emacs, use `org-roam` |
|
|
|
When you start `org-roam` (e.g. via `org-roam-mode`), now you should no longer see the "No EmacSQL SQLite binary available, aborting" error. You are good to go. |
|
|
|
|
|
### emacsql-sqlite3 |
|
|
|
1. In Emacs, install the `emacsql-sqlite3` package |
|
|
|
2. Using your text editor, etc. modify `org-roam-db.el`: |
|
|
|
1. Replace `(require 'emacsql-sqlite)` with `(require 'emacsql-sqlite3)` |
|
|
|
2. Comment/deactivate the complete `(defconst org-roam-db--sqlite-available-p ... )` |
|
|
|
3. In `(defun org-roam-db ...`, replace `emacsql-sqlite` |
|
with `emacsql-sqlite3` |
|
|
|
3. If you compile `.el` files, ensure to replace `org-roam-db.elc` with the new source you modified.
|
|
|