forked from technomancy/emacs-starter-kit
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
adds a README on how this branch will look like
- Loading branch information
Showing
1 changed file
with
37 additions
and
117 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,122 +1,42 @@ | ||
| # Emacs Starter Kit | ||
| # .emacs.d | ||
|
|
||
| The Starter Kit should provide a saner set of defaults than you get | ||
| normally with Emacs. It was originally intended for beginners, but it | ||
| should provide a reasonable working environment for anyone using Emacs | ||
| for dynamic languages. It also bundles a number of useful libraries | ||
| that are not distributed with Emacs for various reasons. | ||
| This emacs setup was bootstrapped with [techomancy's emacs-starter-kit](http://github.com/technomancy/emacs-starter-kit/). | ||
| It has been updated to use version 2 of the starter kit. | ||
|
|
||
| The latest version is at http://github.com/technomancy/emacs-starter-kit/ | ||
|
|
||
| ## Learning | ||
|
|
||
| This won't teach you Emacs, but it'll make it easier to get | ||
| comfortable. To access the tutorial, press control-h followed by t. | ||
|
|
||
| You may also find the [PeepCode Meet Emacs | ||
| screencast](http://peepcode.com/products/meet-emacs) helpful. The | ||
| [Emacs Wiki](http://emacswiki.org) is also very handy. | ||
| The goal of this project is to facilitate the sharing of a common emacs setup | ||
| within a company (or anyone really). ELPA packages are the preferred way | ||
| to bring in dependencies but in many cases this is not possible so git submodules | ||
| or just committed files are used. See the section on Structure for more details. | ||
|
|
||
| ## Installation | ||
|
|
||
| 1. Install GNU Emacs (at least version 22, 23 is preferred) | ||
| Use your package manager if you have one. | ||
| Otherwise Mac users may get [some prebuilt binaries](http://emacsformacosx.com/), and | ||
| Windows users can get them [from GNU](http://ftp.gnu.org/pub/gnu/emacs/windows/emacs-23.1-bin-i386.zip). | ||
| 2. Move the directory containing this file to ~/.emacs.d | ||
| (If you already have a directory at ~/.emacs.d move it out of the | ||
| way and put this there instead.) | ||
| 3. Launch Emacs! | ||
|
|
||
| If you find yourself missing some autoloads after an update (which | ||
| should manifest itself as "void function: foobar" errors) try M-x | ||
| regen-autoloads. After some updates an M-x recompile-init will be | ||
| necessary; this should be noted in the commit messages. | ||
|
|
||
| If you want to keep your regular ~/.emacs.d in place and just launch a | ||
| single instance using the starter kit, try the following invocation: | ||
|
|
||
| $ emacs -q -l ~/src/emacs-starter-kit/init.el | ||
|
|
||
| Note that having a ~/.emacs file might override the starter kit | ||
| loading, so if you've having trouble loading it, make sure that file | ||
| is not present. | ||
|
|
||
| ## Structure | ||
|
|
||
| The init.el file is where everything begins. It's the first file to | ||
| get loaded. The starter-kit-* files provide what I consider to be | ||
| better defaults, both for different programming languages and for | ||
| built-in Emacs features like bindings or registers. | ||
|
|
||
| Files that are pending submission to ELPA are bundled with the starter | ||
| kit under the directory elpa-to-submit/. The understanding is that | ||
| these are bundled just because nobody's gotten around to turning them | ||
| into packages, and the bundling of them is temporary. For these | ||
| libraries, autoloads will be generated and kept in the loaddefs.el | ||
| file. This allows them to be loaded on demand rather than at startup. | ||
|
|
||
| There are also a few files that are meant for code that doesn't belong | ||
| in the Starter Kit. First, the user-specific-config file is the file | ||
| named after your user with the extension ".el". In addition, if a | ||
| directory named after your user exists, it will be added to the | ||
| load-path, and any elisp files in it will be loaded. Finally, the | ||
| Starter Kit will look for a file named after the current hostname | ||
| ending in ".el" which will allow host-specific configuration. This is | ||
| where you should put code that you don't think would be useful to | ||
| everyone. That will allow you to merge with newer versions of the | ||
| starter-kit without conflicts. | ||
|
|
||
| ## Emacs Lisp Package Archive | ||
|
|
||
| Libraries from [ELPA](http://tromey.com/elpa) are preferred when | ||
| available since dependencies are handled automatically, and the burden | ||
| to update them is removed from the user. In the long term, ideally | ||
| everything would be installed via ELPA, and only package.el would need | ||
| to be distributed with the starter kit. (Or better yet, package.el | ||
| would come with Emacs...) See starter-kit-elpa.el for a list of | ||
| libraries that are pending submission to ELPA. Packages get installed | ||
| in the elpa/ directory. | ||
|
|
||
| There's no vendor/ directory in the starter kit because if an external | ||
| library is useful enough to be bundled with the starter kit, it should | ||
| be useful enough to submit to ELPA so that everyone can use it, not | ||
| just users of the starter kit. | ||
|
|
||
| Sometimes packages are removed from the Starter Kit as they get added | ||
| to ELPA itself. This has occasionally caused problems with certain | ||
| packages. If you run into problems with such a package, try removing | ||
| everything from inside the elpa/ directory and invoking M-x | ||
| starter-kit-elpa-install in a fresh instance. | ||
|
|
||
| ## Variants of Emacs | ||
|
|
||
| The Starter Kit is designed to work with GNU Emacs version 22 or | ||
| greater. Using it with forks or other variants is not supported. It | ||
| probably won't work with XEmacs, though some have reported getting it | ||
| to work with Aquamacs. However, since Aquamacs is not portable, | ||
| it's difficult to test in it, and breakage is common. | ||
|
|
||
| ## Contributing | ||
|
|
||
| If you know your way around Emacs, please try out the starter kit as a | ||
| replacement for your regular dotfiles for a while. If there's anything | ||
| you just can't live without, add it or let me know so I can add | ||
| it. Take a look at what happens in init.el to get started. | ||
|
|
||
| Also: see the file TODO. Helping submit new libraries to ELPA is the | ||
| easiest way to help out. There are two ways you can do this: either | ||
| take new libraries and make them ready for ELPA, dropping them in the | ||
| elpa-to-submit directory or take files that are already in | ||
| elpa-to-submit, ensuring all their dependencies are correctly loaded | ||
| into ELPA, and sending them to the ELPA maintainer. There are details | ||
| at http://tromey.com/elpa/upload.html for how ELPA submission | ||
| works. Grep the project for TODO for other things. | ||
|
|
||
| Files are licensed under the same license as Emacs unless otherwise | ||
| specified. See the file COPYING for details. | ||
|
|
||
| The latest version is at http://github.com/technomancy/emacs-starter-kit/ | ||
|
|
||
| On Unix, /home/$USER/.emacs.d, on windows Documents and Settings/%your | ||
| user name%/Application Data | ||
| You'll need Emacs 24, which comes with package.el. It's not hard to | ||
| compile [from source](http://github.com/emacsmirror/emacs), but | ||
| precompiled versions are readily available for | ||
| [Debian-based systems](http://emacs.naquadah.org/), | ||
| [Mac OS X](http://emacsformacosx.com/builds), and | ||
| [Windows](http://code.google.com/p/emacs-for-windows/updates/list). | ||
|
|
||
| Clone this project as `~/.emacs.d` and launch emacs! | ||
|
|
||
| ## Structure and Sharing | ||
|
|
||
| The `init.el` file is where everything begins and is shared by everyone. | ||
| As such, this file should remain as general as possible and not include | ||
| user specific configuration at all. Your user-specific-config should be | ||
| held in `your-user-name.el` and the Starter Kit will load it. Additionally, | ||
| the Starter Kit also allows host-specific configuration by loading | ||
| `your-hostname.el`. Emacs' "custom" library is configured to save it's | ||
| settings to `your-user-name-custom.el`. The advantage of this is that it won't | ||
| clutter any of your regular configuration files. By naming it after your login | ||
| you can still commit it to a shared repo (if you want) so others can get | ||
| ideas from your customizations. | ||
|
|
||
| The main way to share various customizations and modes is via "initializers". | ||
| The `initializers.available` contains all the actual initializers. An initializer | ||
| may install ELPA packages via the provided `ensure-packages-installed` function, or | ||
| append to the load-path code from the `vendor` path. Either way, the | ||
| initializers should try to use `autoload` instead of `require` or `load.` The best | ||
| way to get an idea of what an initializer does is just to look at a few. To enable | ||
| an initializer you need to add a corresponding symlink to it in `initializers.enabled`. | ||
| Upon startup all the initializers found in `initializers.enabled` will be loaded. |