Copyright © 1995-2009 Jari Aalto
License: This material may be distributed only subject to the terms and conditions set forth in GNU General Public License v2 or later; or, at your option, distributed under the terms of GNU Free Documentation License version 1.2 or later (GNU FDL).
Emacs Tiny Tools is a collection of libraries and packages, which are designed to be OS and X/Emacs platform independent. E.g. configure load-path automatically, URL handler, easy-delete, mail complete and many more. This file is README.txt included in Emacs Tiny Tools kit. It contains instructions how to install a cross platform Emacs/XEmacs/ Unix/Win32 compatible utilities for wide variety of tasks: diff/patch; searching, replacing, caching files, automatic load-path setup and more.
Extract the package and it will create directory according to the version number. Under Windows platform: create directories manually e.g. on C:\home\elisp and use some suitable archiver program. A Windows environment variable HOME must alse be defined to point to suitable location, like C:\home.
$ mkdir -p $HOME/elisp/packages/
$ mkdir -p $HOME/elisp/config # configuration settings
$ mkdir -p $HOME/tmp # for temporary files
$ cd $HOME/elisp/packages/
$ gzip -dc ~/tmp/download/emacs-tiny-tools*.gz | tar -xvf - |
Emacs load-path must be configured to point to Emacs Lisp package directories. Add following lines to $HOME/.emacs startup file. Substitute the paths as necessary to reflect unpack locations:
(add-to-list 'load-path
"~/elisp/packages/emacs-tiny-tools/lisp/tiny")
(add-to-list 'load-path
"~/elisp/packages/emacs-tiny-tools/lisp/other") |
1.4.1 Personal install using tinypath
The following lines below will configure Emacs to be aware of all lisp paths under $HOME/elisp or $HOME/lisp, so whatever magic you used to do to keep your load-path up to date is no longer needed. The Lisp package path variable load-path is periodically kept up to date without manual tweaking.
;; $HOME/.emacs
;; This line loads package "tinypath.el"
(load "~/elisp/packages/tiny-tools/lisp/tiny/tinypath")
;; ... rest of the startup
;; End of example |
When the tinypath.el package is active, you can pretty much put packages or individual lisp files anywhere, provided that they reside under $HOME/elisp. you can create or delete directories and move files around to organize your lisp files. The only restriction is that you do not use any symlinks; not to directories or not to files (reason is explained in file tinypath.el). Let's suppose the hierarchy of lisp files look something like this:
$HOME/elisp/
|
+-packages/
| |
| + package-1.NNNN/
| + package-2.NN/
+-other/
+-my/ |
Now, perhaps you see an utility.el in gnu.emacs.sources that you would like to use. How do you install it? Just drop it in, say, to $HOME/elisp/other/ directory and call M-x tinypath-cache-regenerate. After that Emacs knows the package in next Emacs sessions. You still have to add relevant lines to your Emacs startup which make the package active. Look inside utility.el and its setup instructions, something like:
(load "utility")
(utility-install) ;; or whatever is needed to activate it |
1.4.2 Site wide install using tinypath
If you are administering the current host and you have both XEmacs and Emacs installations; plus you have lot of extra Emacs packages that are available form the Net, you need to tell the different locations where the installed lisp directories are. In this case, you have to set the tinypath-:load-path-root. In previous personal installation example, this was automatically determined.
After the code below, user have access to all packages installed to your system, no matter where they reside. The load-path is configured porperly at Emacs startup and you, the admin, can concentrate on getting your hand on the most prospective lisp packages. Just drop them anywhere, move them around, the changes will be noticed automatically.
;; <emacs-version>/lisp/site-start.el
;;
;; List of ROOT directories where all Emacs lisp
;; files are located. Update list according to your site.
;; No need to optimize away non-existing directories,
;; because they will be ignored.
(setq tinypath-:load-path-root
(list
(if (boundp 'xemacs-logo) ;; ROOT DIR ONE
"The-XEmacs-root/lisp"
"The-Emacs-root/lisp")
(if (boundp 'xemacs-logo) ;; ROOT DIR TWO
"Your-XEmacs-site-list-directory"
"Your-Emacs-site-list-directory")
"~/elisp" ;; ... and so on
"~/lisp"))
(load "/path/to/tinypath.el")
;; End of example |
The autoload file provide "functions" that are made known to Emacs, but they do not load any packages. This is better than using require or load commands, because it makes the Emacs start faster.
;; $HOME/.emacs
(load "/path/to/tinypath.el")
;; Load files that tell what functions exist
(require 'tiny-autoload-loaddefs-tiny)
(require 'tiny-autoload-loaddefs-other)
;; Now, configure packages you want, See each package
;; for further instructions
(autoload 'turn-on-tinyperl-mode "tinyperl" "" t)
(add-hook 'perl-mode-hook 'turn-on-tinyperl-mode)
(add-hook 'cperl-mode-hook 'turn-on-tinyperl-mode)
;; End of $HOME/.emacs |
If you are tight of space or otherwise do not need all the tools or if you're only interested in specific package, a minimum installation is possible. The basic idea is to include libraries + needed package(s).
tinyliba.el - autoloads
tinylibb.el - backward compatibility; Emacs version changes
tinylibm.el - macros and other low level forms
tinylib.el - main library
tinylibxe.el - XEmacs support library
+ NOW select packages that you're interested in. |
IT IS IMPORTANT THAT YOU USE NON-COMPILED FILES AND SUBMIT THE BACKTRACE. Send a bug report by using package's contact functions. The XXX below refers to the function prefix, like tinyurl for package tinyurl.el:
M-x load-library RET package.el RET # load non-compiled
M-x turn-on-emacs-debug RET # From tinyliba.el
... repeat what you did until the point of error ...
M-x XXX-submit-bug-report << prefer this if it exists >>
M-x XXX-submit-feedback
... and copy paste any relevant information, like the lisp
... error buffer *Backtrace* that might have been generated. |
The first package made was tinyappend.el, a simple utility to gather selected areas of text somewhere convenient. Since then the prefix "tiny" has been preserved in front of every lisp file. The word has no other meaning.
The life with Emacs evolved in the direction called "Tiny Tools"; modules that got initially written in the past years starting with Emacs 18.59 and after that with 19.28. The current code is aimed to be XEmacs/Emacs Unix/Win32 platform independent. The cross platform could not be possible without following testers that patiently kept reporting bugs and making improvement suggestions. Most sincere thanks to you all.
Please read these instructions with some salt, because the they may not be 100% accurate for later Emacs versions. Feel free to suggest corrections to this text.
All the files in Tiny Tools kit turn on the dynamic byte compilation flag, which appeared in Emacs 19.29 and XEmacs 19.14. That's something you don't have to worry about, but I think you are would be interested in hearing, that it has some nice benefits over the normal compilation. If you say
(require 'tinylibm) |
the statement used to mean "load library tinylibm". All functions were imported into emacs in a whip. But that's different now with dynamically compiled files. Now it means "load STUBS from library tinylibm". The STUBS are pointers in a table to all the rest of the functions in the library. So, the functions are not actually loaded to your Emacs; neither does your Emacs suffer from sudden memory bloat.
When the actual function is called, Emacs automatically substitutes the STUB with the function definition by loading it from the library. Just that function, not the others. That's the benefit of the dynamic byte compilation in a nutshell.
By the way, if you happen to need some function from the libraries, don't do this:
(require 'tinylimt) ;; mail tools |
Do not do this either, if you need something from the main library:
(require 'tinylib) |
The correct way to let your emacs know about all the existing library functions, is to load the m library. It will define all the necessary autoloads to rest of the function and you don't have to worry about the location of a particular function
;; Define everything, publish interfaces. Defines
;; backward compatibility functions, autoloads etc.
(require 'tinylibm) |
When you install packages, try to avoid loading them from your $HOME/.emacs like this
(require 'tinytab) ;; TAB minor mode |
Because it means that the whole package is loaded (or STUBS) if you do have many require commands, your Emacs startup time grows proportionally. You hate slow Emacs startup; right? Okay, there is much better way to load files; called autoload. It means that you tell Emacs; that "function exists in package xxx". When function or feature is called (and the autoload triggers), Emacs loads function from the package. Some day you don't use some feature in your emacs, sometimes you use, and Emacs grows and loads the packages when you happen to need them. No need to use require to have it all at once.
Now, if you read carefully the installation section from every package and prefer copying the autoload setup instead, you will have the most optimized way to install the package to your .emacs. If some package doesn't have autoload choice, complain immediately to the Author. The package writer should have thought the autoload possibility too. There may also be a note that package can't be autoloaded, so in that case there is no other possibility that to require it. For even more slicker and faster Emacs startup sequence, see package TinyLoad which you can uset to optimise lisp file loadings even more.
Emacs releases come with the package defcustom.el bundled. If you have limited lisp skills or if you want an easy interface to packages' variables, then you can customize the modules. The group is completed when you press tab key:
M-x customize-group RET group RET |
This file has been automatically generated from plain text file with
t2html
Last updated: 2008-09-15 15:20