X-Git-Url: https://git.shemshak.org/gitweb.cgi/~bandali/configs/blobdiff_plain/d31ff102310a091b5797d5d99315d4dc27bf90cf..1eea0aec80cdffdf238cef55ef4596eccd8b22dd:/init.org?ds=inline

diff --git a/init.org b/init.org
index c256b7f..7e82b73 100644
--- a/init.org
+++ b/init.org
@@ -32,6 +32,46 @@ anyway.  So, I've opted to use =straight.el=.  I also used Borg for a
 few months, but decided to try =straight.el= which allows direct use
 of the various package archives.
 
+** Installation
+
+To use this config for your Emacs, first you need to clone this repo,
+then tangle =init.org= into =init.el=, and optionally byte-compile
+=init.el=.
+
+First, clone the repository and =cd= into it:
+
+#+begin_src sh :tangle no
+git clone https://git.sr.ht/~bandali/dotfiles ~/.emacs.d
+cd ~/.emacs.d
+#+end_src
+
+Then, decide if you would like to use a byte-compiled init file, and
+set the following variable accordingly:
+
+#+begin_src emacs-lisp
+(defvar a/byte-compiled-init t
+  "If non-nil, byte-(re)compile init.el on successful tangles.")
+#+end_src
+
+Now, first tangle =init.org=, and only if you chose to have a
+byte-compiled init, build init as well:
+
+#+begin_src sh :tangle no
+make tangle-init
+make build-init
+#+end_src
+
+If you'd like to use a byte-compiled init, it's important that it be
+recompiled whenever =init.el= is generated from an updated =init.org=.
+Not only does my setup automatically and asynchronously tangle
+=init.org= to =init.el= every time you edit and save =init.org= in GNU
+Emacs, it will also invoke =make build-init= if you set
+=a/byte-compiled-init= to =t= above, so you wouldn't have to worry
+about manually tangling and compiling your init file whenever you
+change it.  The output of the last byte-compilation in the current
+session is kept in a =*compilation*= buffer, which will automatically
+be displayed if compilation fails.
+
 * Contents                                                   :toc_1:noexport:
 
 - [[#about][About]]
@@ -256,11 +296,13 @@ and without compromising on performance.
 
 #+begin_src emacs-lisp
 (straight-use-package 'use-package)
-(if nil  ; set to t when need to debug init
-    (setq use-package-verbose t
-          use-package-expand-minimally nil
-          use-package-compute-statistics t
-          debug-on-error t)
+(if nil                             ; set to t when need to debug init
+    (progn
+      (setq use-package-verbose t
+            use-package-expand-minimally nil
+            use-package-compute-statistics t
+            debug-on-error t)
+      (require 'use-package))
   (setq use-package-verbose nil
         use-package-expand-minimally t))
 
@@ -854,9 +896,13 @@ file.
   (defvar a/show-async-tangle-time nil
     "Show the time spent tangling the file.")
 
-  (defvar a/async-tangle-post-compile "make bi"
+  (defvar a/async-tangle-post-compile
+    (when a/byte-compiled-init "make build-init")
     "If non-nil, pass to `compile' after successful tangle.")
 
+  ;; TODO: look into why directly byte-compiling init.el causes a
+  ;; number of problems, including magit-status not loading (busy
+  ;; waiting).
   (defvar a/async-tangle-byte-recompile nil
     "If non-nil, byte-recompile the file on successful tangle.")