mirror of
https://github.com/beyondx/Notes.git
synced 2026-02-06 11:53:55 +08:00
246 lines
18 KiB
Plaintext
246 lines
18 KiB
Plaintext
Content-Type: text/x-zim-wiki
|
||
Wiki-Format: zim 0.4
|
||
Creation-Date: 2012-01-07T13:45:24+08:00
|
||
|
||
====== el-get ======
|
||
Created Saturday 07 January 2012
|
||
https://github.com/dimitri/el-get
|
||
|
||
Short Story: el-get allows you to install and manage elisp code for Emacs. It supports lots of** differents types of sources** and is able to **install them, update them and remove them**, but more importantly it will __init __them for you.
|
||
|
||
That means it will __require__ the **features** you need,__ load__ the necessary files, set the__ Info__ paths so that C-h i shows the new documentation you now depend on, and finally __call__ your own** :post-init** function for you to setup the extension. Or call it a package.
|
||
|
||
===== Status and Version Numbers =====
|
||
Current el-get status is stable, ready for daily use and packed with extra features that make life easier. There are some more things we could do, as always, but they will be about smoothing things further.
|
||
|
||
==== • Latest released version ====
|
||
el-get version 3.1 is available, with a boatload of features, including **autoloads **support, **byte-compiling** in an external "clean room" Emacs instance,__ custom__ support,__ lazy initialisation__ support (defering all init functions to //eval-after-load//), and multi repositories ELPA support.
|
||
|
||
==== • Version numbering ====
|
||
Version String are now inspired by how Emacs itself numbers its versions. First is the **major **version number, then a dot, then the **minor** version number. The minor version number is 0 when still developping the next major version. So 3.0 is a developer release while 3.1 will be the next stable release.
|
||
Please note that this versioning policy has been picked while backing 1.2~dev, so 1.0 was a "stable" release in fact. Ah, history.
|
||
|
||
===== How to Install it? =====
|
||
|
||
Here’s the **lazy installer（先安装el-get文件，然后将相关代码添加到启动文件中，当emacs下次启动时会自动下载安装相应的软件包）**:
|
||
;; So the idea is that you copy/paste this code into your *scratch* buffer,
|
||
;; hit C-j, and you have a working el-get.
|
||
(url-retrieve
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el"
|
||
(lambda (s)
|
||
(end-of-buffer)
|
||
(eval-print-last-sexp)))
|
||
|
||
You have to type__ C-j __with the cursor at the end of the last line, but** still on** the line. C-j runs the command// eval-print-last-sexp//, so it will evaluate the code you’re looking at, and that will git clone el-get at the right place.
|
||
|
||
上面的代码只是**下载**el-get安装文件到本地目录，并没有启动和配置它。所以需要把下面的**启动代码**添加到emacs的启动文件中。
|
||
Note that you can add this elisp code into your **emacs init file** directly, as the installer code will detect if el-get is already installed. Notice that doing so directly will require internet access to start emacs. You can avoid this with the following snippet instead:
|
||
把下面的代码添加到emacs的启动文件中.emacs
|
||
|
||
(add-to-list 'load-path "~/.emacs.d/el-get/el-get") ;;注意，加载的目录路径。
|
||
|
||
;;;如果已经下载到本地了则不需要重新下载。
|
||
(unless (require 'el-get nil t)
|
||
(url-retrieve
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el"
|
||
(lambda (s)
|
||
(end-of-buffer)
|
||
(eval-print-last-sexp))))
|
||
|
||
See next section for details about how to setup you emacs so that it’s able to benefit from el-get automatically.
|
||
|
||
===== How to install the developer version (master branch)? =====
|
||
The lazy installer uses the default el-get-install.el file which targets the **2.stable branch**. To install el-get directly on the **master branch**, summon the el-get-master-branch variable into existence:
|
||
|
||
;; So the idea is that you copy/paste this code into your *scratch* buffer,
|
||
;; hit C-j, and you have a working developper edition of el-get.
|
||
(url-retrieve
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el"
|
||
(lambda (s)
|
||
(let (el-get-master-branch)
|
||
(end-of-buffer)
|
||
(eval-print-last-sexp))))
|
||
|
||
|
||
===== Basic usage =====
|
||
Now that el-get is installed, simply use__ M-x el-get-install__ and pick whatever package you need. Arrange to have el-get part of your setup, so that at** next emacs startup the installed packages are initialized**. Here’s how to:
|
||
可以直接使用el-get-install安装自带的sources中的扩展，也可以在.emacs等配置文件中添加**扩展列表**，这样emacs下次启动时就会安装和初始化这些扩展。
|
||
注意：__只有__添加在配置文件中的扩展，el-get才会在启动时自动加载并初始化它们。因此通过el-get-install方式安装的扩展，需要在下面的配置文件中el-get-sources中添加相应的package name。
|
||
|
||
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")
|
||
|
||
(unless (require 'el-get nil t)
|
||
(with-current-buffer
|
||
(url-retrieve-synchronously
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el")
|
||
(end-of-buffer)
|
||
(eval-print-last-sexp)))
|
||
|
||
**(el-get 'sync)**
|
||
|
||
That’s the basic setup.
|
||
|
||
===== Advanced setup with local recipes =====
|
||
Of course, my emacs setup is managed in a private git repository. Some people on //#emacs// are using //git submodules //(or was it straight import) for managing external repositories in there, but all I can say is that I frown on this idea. I want an easy canonical list of packages I depend on to run emacs, and I want this documentation to be usable as-is. Enters el-get!
|
||
|
||
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")
|
||
(require 'el-get)
|
||
|
||
;; local sources ;;非el-get自带的sources，如果name和自带的相同，则这里的设置会**覆盖**自带里的设置。
|
||
(setq __el-get-sources__
|
||
'((:name magit
|
||
:after (lambda () (global-set-key (kbd "C-x C-z") 'magit-status)))
|
||
|
||
(:name asciidoc
|
||
:type elpa
|
||
:after (lambda ()
|
||
(autoload 'doc-mode "doc-mode" nil t)
|
||
(add-to-list 'auto-mode-alist '("\\.adoc$" . doc-mode))
|
||
(add-hook 'doc-mode-hook '(lambda ()
|
||
(turn-on-auto-fill)
|
||
(require 'asciidoc)))))
|
||
|
||
(:name lisppaste :type elpa)
|
||
(:name emacs-goodies-el :type apt-get)))
|
||
|
||
(setq my-packages
|
||
(append
|
||
'(cssh el-get switch-window vkill google-maps nxhtml xcscope yasnippet) ;;这个列表里的扩展来自**自带**的sources
|
||
(mapcar 'el-get-source-name el-get-sources)))
|
||
|
||
(el-get 'sync my-packages) #注意, el-get的配置一般以该命令结束。
|
||
|
||
So now you have a pretty good documentation of the packages you want installed, **where** to get them, and **how** to install them. For the advanced methods (such as **elpa** or **apt-get**), you basically just need the **package name.（因为el-get会自动调用系统的包管理系统来安装它们）。** When relying on a bare git repository, you need to give some more information, such as the** URL** to clone and the** build** steps if any. Then also what **features **to require and maybe where to find the **texinfo** documentation of the package, for automatic inclusion into your local Info menu.
|
||
|
||
The good news is that not only you now have a solid readable description of all that **in a central place**, but this very description is all (el-get) needs to do its magic. This command will __check__ that each and every package is installed on your system (in __el-get-dir__) and if that’s not the case, it will **actually install it**. Then, it will__ init__ the packages: that means caring about the __load-path__, the__ Info__-directory-list (and dir texinfo menu building) the__ loading__ of the emacs-lisp files, and finally it will __require__ the features.
|
||
emacs每次启动时，el-get都会检查el-get命令的参数列表中的各扩展是否安装到系统的el-get-dir变量指定的目录中，如果没有则自动下载并安装它们。然后初始化相关的软件包如：添加load-path变量，load相关文件，require相关文件等（这些初始化配置信息可以在:after、:featers、:info、:load-path等属性中指定）。
|
||
|
||
===== How to use it? =====
|
||
You see that el-get-sources example up there? It **finishes with a single (el-get) call**. That’s it. It will__ install__ new sources **on the list** and only__ init __already installed ones.
|
||
如果已经安装（如直接通过el-get-install命令）的package但没有添加到该list中，则el-get不会初始化它们。
|
||
|
||
The status of each package is tracked into __~/.emacs.d/el-get/.status.el__ (by default，__由el-get-dir变量指定安装包的位置，默认为~/.emacs.d/el-get__) and can get the values required, installed or removed.
|
||
|
||
===== Sync or async? =====
|
||
Most often you want **el-get-install** and **el-get-build **to stay out of the way and be //asynchronous//, so that you can continue using Emacs while your new package is getting ready. But imagine you’re starting up Emacs after a **git pull** on the other computer (after a commute, say), and there’s some newer packages for this instance to consider installing.
|
||
|
||
Now you want a synchronous install, right?
|
||
|
||
So, by default (el-get) is __asynchronous__, but you can ask for it to be sync, or to still be asynchronous but to wait until it finished before to give control back:
|
||
|
||
(el-get 'sync) #异步更新
|
||
(el-get 'wait) #接着添加这条命令后，变为同步更新。
|
||
|
||
You even get a progress report!
|
||
|
||
===== Sources =====
|
||
See the documentation of the __el-get-sources__ variable for details. Please note that el-get-sources is another source location for recipes, adding to your **el-get-recipe-path**.
|
||
注意，可以el-get-recipe-path变量来指定__sources目录，这样el-get会自动到相关目录搜索要安装的package的配置文件__。
|
||
|
||
Note that you can also give a mix of **packages symbols**,** inline recipes **and **source lists** to __el-get__ as arguments, and completely** bypass **the el-get-sources variable.
|
||
|
||
(el-get 'sync) ;**;不指定参数时，默认使用el-get-sources类表中的packages**
|
||
(el-get 'sync 'package 'name 'list-of-packages-names-or-symbol)
|
||
|
||
It is still __recommended__ to (setq el-get-sources '(list of packages)) then use (el-get 'sync), so that commands such as **el-get-update** know which packages to update.
|
||
但是最好还是使用el-get-sources参数来指定安装的package(不管是来之本地的sources还是自带的sources)，这样其它的__默认使用该变量__的命令才可以正常工作。
|
||
|
||
===== Recipes =====
|
||
Some sources are contributed to el-get **directly**, so that you only have to put in the el-get-sources the__ name of the package__ you want to install.
|
||
Should you need some **local specific setup(本地化配置，但还是使用自带的文件下载安装扩展)**, you can do that by providing __a partial sources__ missing the** :type **property: your local properties will get __merged into__ the recipes one.(在el-get初始化代码中指定。)
|
||
|
||
Also, the variable __el-get-recipe-path__ allows you to maintain** local recipes **in case you either dislike the default one or are crafting some new one not commited to the main repository yet. But please do consider sending them over!
|
||
如果想在一个单独的文件里本地化配置自带的软件包，要注意文件中不要有:type属性，同时该文件要在自带的文件__前__加载。因此，该文件所在的目录要在el-get的recipes__前被搜索到__。
|
||
|
||
We do not intend to provide recipes for advanced types such as apt-get and elpa because there’s so little to win here, and maintaining a package list would take too much time.
|
||
|
||
===== Package setup =====
|
||
The package setup can either go into the __:after function__, or in a file named __init-package.el__ in __el-get-user-package-directory__. Any such named file will get automatically loaded by el-get at init time, if it exists.
|
||
|
||
===== Build Commands =====
|
||
__Avoid using make install__, which will usually move files into a "system location." In our case, you probably just want your package //foo// to be all installed into //~/.emacs.d/el-get/foo(实际安装位置的顶级目录由//__el-get-dir变量指定__//)//, right? So, no make install.
|
||
|
||
===== Byte Compiling =====
|
||
el-get will byte compile the elisp for the package when its **source definition** includes a__ :compile__ property set to the** list** of files to byte compile (or to a single file), or __all__ the .el files found in the package when there’s** no :build** command.
|
||
|
||
===== Hooks =====
|
||
el-get offers a variety of specific hooks (read the source), and two general purposes hooks facilities: **el-get-post-install-hooks **and **el-get-post-update-hooks**, called with the package name as argument.
|
||
|
||
===== Some more commands? =====
|
||
Yes, ok.
|
||
|
||
* M-x el-get-list-packages
|
||
Opens a buffer listing **all known packages** (those for which you have a recipe). The listing includes the package name, its status (one of "available", "installed", "removed" or "required") and the package description. The description is a free form text and has not been provided for all recipes. Please also note that el-get-emacswiki-refresh will create recipes omitting the description as of now.
|
||
|
||
* M-x el-get-describe
|
||
Prompt for a package name, **with completion**, then open an Help window with details about the selected package. Those include current status, website, description,__ installation method__, full recipe, and buttons to easily install, update or remove the package.
|
||
显示一个package的详细安装、移除、**配置信息**。
|
||
|
||
* M-x el-get-install
|
||
Will prompt for a package name, with completion, then install it. It will only propose packages that are not already installed. Any package that you have a recipe for is a candidate.
|
||
Please note that when installing a package that is__ not in your el-get-sources or your el-get call means that it will not be initialized__ for you automatically at **emacs startup**. You get a WARNING message when that’s the case.
|
||
所以，使用el-get-install命令安装的package可能不会被自动配置。需要手动地将它们添加到el-get-sources中。
|
||
|
||
* M-x el-get-cd
|
||
Will prompt for an installed package name, with completion, then open its directory with dired.
|
||
|
||
* M-x el-get-update
|
||
Will prompt for an __installed__ package name, with completion, then update it. This will run the build commands and** init **the package again.
|
||
|
||
* M-x el-get-self-update
|
||
Update only one package, el-get itself.
|
||
|
||
* M-x el-get-update-all
|
||
Will update all packages **used in el-get-sources**. Beware that using this function can lead to hours of settings review: more often than not updating a package requires some adjustments to your setup. Updating all of them at once will require reviewing almost all your setup.
|
||
|
||
* M-x el-get-reload
|
||
Reload the given package files. Happens automatically at update time too.
|
||
|
||
* M-x el-get-remove
|
||
Will prompt for an installed package name, with completion, then remove it. Depending on the type of the package, this often means simply **deleting the directory** where the source package lies. Sometime we have to use external tools instead (apt-get, e.g.). No effort is made to unload the features.
|
||
|
||
* M-x el-get-find-recipe-file
|
||
Will prompt for the name of a package, with completion, then find-file its recipe file.
|
||
|
||
* M-x el-get-make-recipes
|
||
Will prompt for an existing directory where to __output all your new recipe files__: one file for each entry in el-get-sources that is not just a symbol and that is not found anywhere in **el-get-recipe-path**.
|
||
|
||
* M-x el-get-checksum
|
||
Will prompt for the name of an installed package, with complement, then compute its checksum if the **package type supports** that feature. The checksum is __added to the kill-ring__ so that you’re ready to yank it into your el-get-sources :checksum property if you want to.
|
||
|
||
* M-x el-get-emacswiki-refresh
|
||
Will launch a subprocess that connects to EmacsWiki and fetch from there the list of elisp scripts hosted. Then produce a recipe file per script, and store that in the given directory, which default to ~/.emacs.d/el-get/el-get/recipes/emacswiki/ if you didn’t change **el-get-dir**.
|
||
|
||
===== Useful functions =====
|
||
* el-get-package-types-alist (statuses &rest types)
|
||
Return an alist of package names that are of __given types.__ Only consider packages whose status is **‘member’** of STATUSES, which defaults to installed, required and removed.
|
||
|
||
ELISP> (el-get-package-types-alist** "installed" 'cvs 'emacswiki**)
|
||
((emacs-w3m . cvs)
|
||
(rect-mark . emacswiki)
|
||
(icomplete+ . emacswiki)
|
||
(php-mode-improved . emacswiki)
|
||
(rainbow-delimiters . emacswiki)
|
||
(goto-last-change . emacswiki)
|
||
(emacs-goodies-el . cvs))
|
||
|
||
* el-get-extra-packages (&rest packages)
|
||
Return installed or required packages that **are not **in given package list.
|
||
|
||
ELISP> (el-get-extra-packages dim-packages)
|
||
((verbiste "installed")
|
||
(package "installed"))
|
||
|
||
===== Extending it =====
|
||
Please see the documentation for the **el-get-methods** and provide a patch!
|
||
|
||
Adding __bzr__ support for example was only about writing 2 functions, mostly using copy paste. Here’s the patch: https://github.com/dimitri/el-get/commit/63e9018102bdeb7b6d9136db231adcd983087217#L0R437
|
||
|
||
===== Upgrade Notes =====
|
||
Upgrading to 3.1
|
||
A change has been included so that el-get-sources is now only another source for recipes, and (el-get '…) will now only install and initialize known "required" and "installed" packages.
|
||
The documentation has been updated to detail the new setup.
|
||
If you have packages that have been installed in the past but you no longer want in your setup, here’s how to get them out of the way:
|
||
M-: (el-get-save-package-status "package-name-here" "removed")
|
||
Please review documentation section Advanced setup with local recipes.
|