#+AUTHOR: lambdart
#+EMAIL: lambdart@protonmail.com
#+KEYWORDS: readme, emacs, elisp, autoloads, elisp, package
#+LANGUAGE: en
#+PROPERTY: header-args :tangle no
#+OPTIONS: toc:nil

* Introduction

  Lazy loading (also known as asynchronous loading) is a technique
  commonly used in computer programming to defer initialization of an object
  until the point at which it is needed. It can contribute to efficiency
  in the program's operation if properly and appropriately used.

  The 'autoload' facility lets you register the existence of a function or
  macro, but put off loading the file that defines it.
  The first call to the function automatically loads the proper
  library, in order to install the real definition and other
  associated code, then runs the real definition as if it had
  been loaded all along.

  This library it's capable of monitoring arbitrary directories
  and automatic generate load definitions, also provides interactive
  functions to trigger the described feature.

  This library was designed having vanilla =Emacs= in mind, so if
  you are missing something, it'll be necessary to properly
  extend it.

* Motivation

  Provide an easy (automatic) way to generate =autoloads= from
  other libraries providing =lazy-load= loading across =Emacs=.

  | Lazy-Load | (emacs-init-time)   |
  | No        | 4.871672671 seconds |
  | Yes       | 0.489159734 seconds |

  I also notice that =Emacs= become more stable and fast (guessing),
  because =exotic=, less used libraries, are loaded only when some
  =autoload= registered =function= is invoked.

* Version

  - Alpha: 0.0.8

* Dependencies

  - cl-seq
  - autoloads
  - filenotify
  - dired-aux

* Tested on

  | Emacs   | 27.1 | 28.0 |
  | FreeBSD | 12.1 | 12.2 |
  | OpenBSD |  6.8 |      |

* Installation
** Manually

   Clone =Lazy= repository to an arbitrary location:

   #+BEGIN_SRC sh

   $ git clone https://codeberg.org/lambdart/lazy-load ~/.emacs.d/site-elisp/lazy-load

   #+END_SRC

   Add =Lazy= directory to =load-path= in your
   Emacs initialization file (~init.el~) and load it.

   #+BEGIN_SRC emacs-lisp

   ;; add to load-path
   (add-to-list 'load-path "/replace/me/to/lazy-load/full/path")

   ;; load lazy-load feature
   (require 'lazy-load nil t)

   #+END_SRC

   - Note: For a more dynamic approach:
     - =M-x load-file RET=
     - =M-x load-library RET lazy-load RET=

** Compile

   * Note: Optional (recommended).

   To compile the files to the =Elisp= byte-compiled representation:

   #+BEGIN_SRC sh

   [at-lazy-load-root-directory]$ make

   #+END_SRC

* Usage

  Set the =lazy-load-files-alist= variable, e.g:

  #+BEGIN_SRC emacs-lisp

  (customize-set-variable
   'lazy-load-files-alist
   (list (cons "site-lisp-loaddefs.el"
               (expand-file-name "site-lisp/" user-emacs-directory)))

  #+END_SRC

  and invoke: =M-x lazy-load-update-autolods RET=

  Set the variable =lazy-load-enable-filenotify-flag= to =t= (true), to
  generate the load definitions =autoloads= automatically when the
  monitored directory emits a signal, i.e, when you download (files)
  packages to it.

  It's also possible to invoke =lazy-load-update-directory-autoloads=
  interactively:

  =M-x lazy-load-update-directory-autoloads RET=

  The procedure will ask for the root directory (where packages
  resides) and the referent =<file-name-path>= where the
  load definitions will be saved.

** Require

   After the =loaddefs= was generated just add it to your =init.el=
   and all the other =(require 'packages)= will be unnecessary.

   Example:

   #+BEGIN_SRC emacs-lisp
   (require 'site-lisp-loaddefs)
   #+END_SRC

   That's all! :D

* Customize

  * Note: To see all the options from =Emacs= directly, and to customize it,
    just type: =M-x customize-group RET lazy-load RET=.

  We have a few available options to customize some aspects of =lazy-load=,
  even though the behavior will probably stay the same, it's recommend
  to proper set this variables in your initialization file.

  - =lazy-load-files-alist= :: Associative list of file-names (loaddefs)
    destination and respective source path (root) directory, example:


    #+BEGIN_SRC emacs-lisp
    (list (cons "site-lisp-loaddefs.el"
                (expand-file-name "site-lisp" user-emacs-directory)))
    #+END_SRC

    RESULT: =(("site-lisp-loaddefs.el" . "/home/<user>/.emacs.d/site-lisp"))=

  - =lazy-load-minor-mode-string= :: String to be displayed at mode-line.
    Default: "lazy-load"

  - =lazy-load-enable-filenotify-flag= :: Non-nil means starts to monitor
    the directories listed at `lazy-load-files-alist'.
    Default: nil

  - =lazy-load-debug-messages-flag= :: Non-nil means show debug messages.
    Default: nil

  - =lazy-load-timer-interval= :: Timer interval in seconds, used to
    trigger the timer callback function.
    Default: 8 seconds

  - =lazy-load-idle-seconds= :: Idle timer value that will be used by
    `run-with-idle-timer'.
    Default: 30 seconds

* Commands

  An object which can be invoked via the ‘command-execute’ primitive,
  usually due to the user typing in a key sequence “bound” to that
  command.

  A command is usually a function; if the function is written in Lisp,
  it is made into a command by an ‘interactive’ form in the function
  definition-prefixes.

* References

  1. https://www.gnu.org/software/emacs/manual/html_node/elisp/Autoload.html
  2. https://en.wikipedia.org/wiki/Lazy_loading

* LICENSE
  MIT

* EOF

  #+BEGIN_SRC
  I don't think necessity is the mother of invention.
  Invention arises directly from idleness, possibly also
  from laziness. To save oneself trouble.
  #+END_SRC
  | Agatha Mary Clarissa Miller |