* document package.el @ 2010-08-06 22:42 Tom Tromey 2010-08-06 23:48 ` Phil Hagelberg ` (4 more replies) 0 siblings, 5 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-06 22:42 UTC (permalink / raw To: Emacs discussions I'd appreciate comments on this patch. I finally found a little time to write some documentation for package.el. Tom 2010-08-06 Tom Tromey <tromey@redhat.com> * vol2.texi (Top): Update. * vol1.texi (Top): Update. * tips.texi (Library Headers): Mention Package-Version and Package-Requires. * package.texi: New file. * os.texi (System Interface): Update pointers. * elisp.texi (Top): Link to new nodes. Include package.texi. * anti.texi (Antinews): Update pointers. === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2010-01-13 08:35:10 +0000 +++ doc/lispref/anti.texi 2010-07-30 00:05:33 +0000 @@ -6,7 +6,7 @@ @c This node must have no pointers. -@node Antinews, GNU Free Documentation License, System Interface, Top +@node Antinews, GNU Free Documentation License, Packaging, Top @appendix Emacs 22 Antinews @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries @c with the above version number. === modified file 'doc/lispref/elisp.texi' --- doc/lispref/elisp.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/elisp.texi 2010-07-31 01:32:13 +0000 @@ -159,6 +159,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1394,6 +1396,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. @@ -1490,6 +1498,8 @@ @include display.texi @include os.texi +@include package.texi + @c MOVE to Emacs Manual: include misc-modes.texi @c appendices === modified file 'doc/lispref/os.texi' --- doc/lispref/os.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/os.texi 2010-07-30 00:05:24 +0000 @@ -5,7 +5,7 @@ @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/os -@node System Interface, Antinews, Display, Top +@node System Interface, Packaging, Display, Top @chapter Operating System Interface This chapter is about starting and getting out of Emacs, access to === added file 'doc/lispref/package.texi' --- doc/lispref/package.texi 1970-01-01 00:00:00 +0000 +++ doc/lispref/package.texi 2010-08-06 22:05:47 +0000 @@ -0,0 +1,149 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2010 +@c Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/os +@node Packaging, Antinews, System Interface, Top +@chapter Preparing Lisp code for distribution + + Emacs provides a standard way for Emacs Lisp code to be distributed +to users. This approach lets users easily download, install, +uninstall, and upgrade Lisp code that they might want to use. + + A @dfn{package} is simply one or more files, formatted and bundled +in a particular way. Typically a package includes primarily Emacs +Lisp code, but it is possible to create other kinds of packages as +well, for example, a package consisting solely of documentation. + +@menu +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. +@end menu + +@node Packaging Basics +@section Packaging Basics + + A package has a few attributes: + +@table @asis +@item Name +A string, the name of the package. + +@item Version +A version number, which is a dotted list of integers, like +@samp{1.2.0.3}. + +@item Brief description +This is shown to the user in the package menu buffer. It is just a +single line. + +@item Long description +This can be a @file{README} file or the like. This is available to +the user before the package is installed, via the package menu. It +should more fully describe the package and its capabilities, so a user +can read it to decide whether he wants to install the package. + +@item Dependencies +This is a list of other packages and their minimal acceptable +versions. This is used both at download time (to make sure all the +needed code is available) and at activation time (to ensure a package +is only activated if all its dependencies have been successfully +activated). + +@item Manual +A package can include an info manual. +@end table + + Conceptually, a package goes through several state transitions (in +reality some of these transitions are grouped together): + +@table @asis +@item Download +Fetch the package from somewhere. + +@item Install +Untar the package, or write a @file{.el} file into the appropriate +install directory. This step also includes extracting autoloads and +byte-compiling the Emacs Lisp code. + +@item Activate +Update @code{load-path} and @code{Info-directory-list} and evaluate +the autoloads, so that the package is ready for the user to use. +@end table + + It is best for users if packages do not do too much work at +activation time. The best approach is to have activation consist of a +some autoloads and little more. + +@node Simple Packages +@section Simple Packages + + The simplest package consists of a single Emacs Lisp source file. +In this case, all the attributes of the package are taken from this +file. + + The package system expects this @file{.el} file to conform to the +Emacs Lisp library header conventions. See @xref{Library Headers}. + + The name of the package is the same as the base name of the +@file{.el} file, as written in the first comment line. + + The short description of the package is also taken from the first +line of the file. + + If the file has a ``Commentary'' header, then it is used as the long +description. + + The version of the package comes either from the ``Package-Version'' +header, if it exists, or from the ``Version'' header. A package is +required to have a version number. + + If the file has a ``Package-Requires'' header, then that is used as +the package dependencies. Otherwise, the package is assumed not to +have any dependencies. + + A single-file package cannot have an info manual. + + The file will be scanned for autoload comments at install time. + +@node Multi-file Packages +@section Multi-file Packages + + A multi-file package is just a @file{.tar} file. While less +convenient to create than a single-file package, a multi-file package +also offers more features: it can include an info manual, multiple +Emacs Lisp files, and also other data files needed by a package. + + The contents of the @file{.tar} file must all appear in a single +directory, named after the package and version. Also, the @file{.tar} +file is typically also given this same name. For example, if you are +distributing version 1.3 of the superfrobnicator, the package file +would be named ``superfrobnicator-1.3.tar'' and the contents would all +appear in the directory @file{superfrobnicator-1.3} in that +@file{.tar}. + + The package must include a @file{-pkg.el} file, named after the +package. In our example above, this file would be called +@file{superfrobnicator-pkg.el}. This file must have a single form in +it, a call to @code{define-package}. The package dependencies and +brief description are taken from this form. + + If a @file{README} file exists in the content directory, then it is +used as the long description. + + If the package has an info manual, you should distribute the needed +info files, plus a @file{dir} file made with @command{install-info}. + + Do not include any @file{.elc} files in the package. Those will be +created at install time. Note that there is no way to control the +order in which files are byte-compiled; your package must be robust +here. + + The installation process will scan all the @file{.el} files in the +package for autoload comments. They are extracted into a +@file{-autoloads.el} file (e.g., +@file{superfrobnicator-autoloads.el}), so do not include a file of +that name in your package. + === modified file 'doc/lispref/tips.texi' --- doc/lispref/tips.texi 2010-06-23 03:36:56 +0000 +++ doc/lispref/tips.texi 2010-07-31 18:43:10 +0000 @@ -1052,6 +1052,31 @@ This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both. + +@item Package-Version +If @samp{Version} is not suitable for use by the package manager, then +a package can define @samp{Package-Version}; it will be used instead. +This is handy if @samp{Version} is an RCS id or something else that is +not a dotted list of integers. + +@item Package-Requires +If this exists, it names packages on which the current package +depends for proper operation. This is used by the package manager +both at download time (to ensure that a complete set of packages is +downloaded) and at activation time (to ensure that a package is +activated if and only if all its dependencies have been). + +Its format is a list of lists. The @code{car} of each sub-list is the +name of a package, as a symbol. The @code{cadr} of each sub-list is +the minimum acceptable version number, as a string. For instance: + +@smallexample +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +@end smallexample + +The package code automatically defines a package named @samp{eamcs} +with the version number of the currently running Emacs. This can be +used to require a minimal version of Emacs for a package. @end table Just about every Lisp library ought to have the @samp{Author} and === modified file 'doc/lispref/vol1.texi' --- doc/lispref/vol1.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol1.texi 2010-07-31 01:32:31 +0000 @@ -180,6 +180,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1415,6 +1417,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. === modified file 'doc/lispref/vol2.texi' --- doc/lispref/vol2.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol2.texi 2010-07-31 01:32:50 +0000 @@ -179,6 +179,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1414,6 +1416,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 22:42 document package.el Tom Tromey @ 2010-08-06 23:48 ` Phil Hagelberg 2010-08-09 16:22 ` Tom Tromey 2010-08-07 1:43 ` Christoph ` (3 subsequent siblings) 4 siblings, 1 reply; 34+ messages in thread From: Phil Hagelberg @ 2010-08-06 23:48 UTC (permalink / raw To: Tom Tromey; +Cc: Emacs discussions On Fri, Aug 6, 2010 at 3:42 PM, Tom Tromey <tromey@redhat.com> wrote: > I'd appreciate comments on this patch. > > I finally found a little time to write some documentation for > package.el. Thanks; this looks great! I've had a number of people ask me about how multi-file packages work, so now I will point them here. The only thing I'd note is that it doesn't mention anything about the user-level settings that control package activation and installation. Perhaps the defcustom docstrings are sufficient for these already? -Phil ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 23:48 ` Phil Hagelberg @ 2010-08-09 16:22 ` Tom Tromey 0 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-09 16:22 UTC (permalink / raw To: Phil Hagelberg; +Cc: Emacs discussions Phil> The only thing I'd note is that it doesn't mention anything about the Phil> user-level settings that control package activation and installation. Phil> Perhaps the defcustom docstrings are sufficient for these already? I didn't know about those. I took a quick look and they all seem to be for users. This documentation is intended for people making packages. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 22:42 document package.el Tom Tromey 2010-08-06 23:48 ` Phil Hagelberg @ 2010-08-07 1:43 ` Christoph 2010-08-07 8:57 ` Geralt ` (3 more replies) 2010-08-07 7:47 ` Eli Zaretskii ` (2 subsequent siblings) 4 siblings, 4 replies; 34+ messages in thread From: Christoph @ 2010-08-07 1:43 UTC (permalink / raw To: emacs-devel; +Cc: tromey On 8/6/2010 4:42 PM, Tom Tromey wrote: > I'd appreciate comments on this patch. > > I finally found a little time to write some documentation for > package.el. Hi Tom, I just tried package.el for the first time and I like it a lot! This could save me a lot of time googling around trying to find the latest versions. I have a couple of thoughts: I am wondering, is there a way to give package.el a list of packages to go download from ELPA and install? I would also want it to use this list to check for new versions of all packages in the list. Either on startup or on command (M-x package-upgrade). Also, on a new installation of Emacs I would just tell it "Go get the packages in the list" and it would recreate my package configuration on that machine. All I need in version control is the list as part of my init.el, instead of putting the entire elpa/ directory under version control and deploying it to the new machine. Great work! Christoph ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 1:43 ` Christoph @ 2010-08-07 8:57 ` Geralt 2010-08-09 16:23 ` Tom Tromey ` (2 subsequent siblings) 3 siblings, 0 replies; 34+ messages in thread From: Geralt @ 2010-08-07 8:57 UTC (permalink / raw To: Christoph; +Cc: emacs-devel Hi, On Sat, Aug 7, 2010 at 3:43 AM, Christoph <cschol2112@googlemail.com> wrote: > I have a couple of thoughts: > I am wondering, is there a way to give package.el a list of packages to go > download from ELPA and install? I would also want it to use this list to > check for new versions of all packages in the list. Either on startup or on > command (M-x package-upgrade). Also, on a new installation of Emacs I would > just tell it "Go get the packages in the list" and it would recreate my > package configuration on that machine. All I need in version control is the > list as part of my init.el, instead of putting the entire elpa/ directory > under version control and deploying it to the new machine. > recently I stumbled upon a package called el-get[1], it basically does what you want, but is more general. It does not only support elpa, but also different version control systems and websites to retrieve packages from. HTH, Geralt. [1]http://blog.tapoueh.org/articles/news/_el-get.html ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 1:43 ` Christoph 2010-08-07 8:57 ` Geralt @ 2010-08-09 16:23 ` Tom Tromey 2010-08-26 23:27 ` Juri Linkov 2010-08-27 6:43 ` Uday S Reddy 3 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-09 16:23 UTC (permalink / raw To: Christoph; +Cc: emacs-devel >>>>> "Christoph" == Christoph <cschol2112@googlemail.com> writes: Christoph> I am wondering, is there a way to give package.el a list of Christoph> packages to go download from ELPA and install? I would also Christoph> want it to use this list to check for new versions of all Christoph> packages in the list. Either on startup or on command (M-x Christoph> package-upgrade). Also, on a new installation of Emacs I Christoph> would just tell it "Go get the packages in the list" and it Christoph> would recreate my package configuration on that machine. There isn't anything like this. I suppose it could be done with a little elisp. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 1:43 ` Christoph 2010-08-07 8:57 ` Geralt 2010-08-09 16:23 ` Tom Tromey @ 2010-08-26 23:27 ` Juri Linkov 2010-08-26 23:50 ` Stefan Monnier ` (2 more replies) 2010-08-27 6:43 ` Uday S Reddy 3 siblings, 3 replies; 34+ messages in thread From: Juri Linkov @ 2010-08-26 23:27 UTC (permalink / raw To: Christoph; +Cc: tromey, emacs-devel > I am wondering, is there a way to give package.el a list of packages to go > download from ELPA and install? I would also want it to use this list to > check for new versions of all packages in the list. Either on startup or on > command (M-x package-upgrade). Also, on a new installation of Emacs I would > just tell it "Go get the packages in the list" and it would recreate my > package configuration on that machine. All I need in version control is the > list as part of my init.el, instead of putting the entire elpa/ directory > under version control and deploying it to the new machine. I guess we need something like `require', e.g. (package-require FEATURE &optional FILENAME NOERROR). So you could put in your .emacs: (package-require 'company) (package-require 'js2-mode) (package-require 'rainbow-mode) and it will take care of installing and activating your preferred packages on a new installation. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-26 23:27 ` Juri Linkov @ 2010-08-26 23:50 ` Stefan Monnier 2010-08-27 3:14 ` Christoph 2010-08-27 3:12 ` Christoph 2010-08-27 7:07 ` Uday S Reddy 2 siblings, 1 reply; 34+ messages in thread From: Stefan Monnier @ 2010-08-26 23:50 UTC (permalink / raw To: Juri Linkov; +Cc: Christoph, tromey, emacs-devel > So you could put in your .emacs: > (package-require 'company) > (package-require 'js2-mode) > (package-require 'rainbow-mode) > and it will take care of installing and activating > your preferred packages on a new installation. Downloading&installing packages from .emacs should not be encouraged. Stefan ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-26 23:50 ` Stefan Monnier @ 2010-08-27 3:14 ` Christoph 2010-08-27 5:51 ` Uday S Reddy 0 siblings, 1 reply; 34+ messages in thread From: Christoph @ 2010-08-27 3:14 UTC (permalink / raw To: Stefan Monnier; +Cc: Juri Linkov, tromey, emacs-devel On 8/26/2010 5:50 PM, Stefan Monnier wrote: > Downloading&installing packages from .emacs should not be encouraged. Why? Christoph ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 3:14 ` Christoph @ 2010-08-27 5:51 ` Uday S Reddy 0 siblings, 0 replies; 34+ messages in thread From: Uday S Reddy @ 2010-08-27 5:51 UTC (permalink / raw To: emacs-devel On 8/27/2010 4:14 AM, Christoph wrote: > On 8/26/2010 5:50 PM, Stefan Monnier wrote: > >> Downloading&installing packages from .emacs should not be encouraged. > > Why? Because if it gets stuck, your Emacs is stuck. A start-up file should do quick and safe configuration actions and return to the user so that he/she can get on with using it. You are free to put whatever you want in your .emacs of course. But that can't be the policy. Cheers, Uday ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-26 23:27 ` Juri Linkov 2010-08-26 23:50 ` Stefan Monnier @ 2010-08-27 3:12 ` Christoph 2010-08-27 7:07 ` Uday S Reddy 2 siblings, 0 replies; 34+ messages in thread From: Christoph @ 2010-08-27 3:12 UTC (permalink / raw To: Juri Linkov; +Cc: tromey, emacs-devel On 8/26/2010 5:27 PM, Juri Linkov wrote: > I guess we need something like `require', > e.g. (package-require FEATURE&optional FILENAME NOERROR). > > So you could put in your .emacs: > > (package-require 'company) > (package-require 'js2-mode) > (package-require 'rainbow-mode) > > and it will take care of installing and activating > your preferred packages on a new installation. Interesting. On each subsequent startup, after installing, it could then check if a new version is available and prompt for update. Of course that could be optional for people who don't want to be bothered with updating on startup. Christoph ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-26 23:27 ` Juri Linkov 2010-08-26 23:50 ` Stefan Monnier 2010-08-27 3:12 ` Christoph @ 2010-08-27 7:07 ` Uday S Reddy 2010-08-27 21:40 ` Phil Hagelberg 2 siblings, 1 reply; 34+ messages in thread From: Uday S Reddy @ 2010-08-27 7:07 UTC (permalink / raw To: emacs-devel On 8/27/2010 12:27 AM, Juri Linkov wrote: > I guess we need something like `require', > e.g. (package-require FEATURE&optional FILENAME NOERROR). > > So you could put in your .emacs: > > (package-require 'company) > (package-require 'js2-mode) > (package-require 'rainbow-mode) > > and it will take care of installing and activating > your preferred packages on a new installation. Separating out the .emacs issue, I think it would indeed be a good idea to have the preferred-package list stored somewhere so that we can use it for new installations. There is the ~/.emacs.d/elpa/archives directory. Would it be possible to copy this to a new installation in order to tell package.el what to install? To tell you the truth, I am quite unclear yet what package.el can do, not having seen a manual for it. Does it exist somewhere? Cheers, Uday ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 7:07 ` Uday S Reddy @ 2010-08-27 21:40 ` Phil Hagelberg 2010-08-28 17:34 ` Tom Tromey 0 siblings, 1 reply; 34+ messages in thread From: Phil Hagelberg @ 2010-08-27 21:40 UTC (permalink / raw To: Uday S Reddy; +Cc: emacs-devel On Fri, Aug 27, 2010 at 12:07 AM, Uday S Reddy <u.s.reddy@cs.bham.ac.uk> wrote: > Separating out the .emacs issue, I think it would indeed be a good idea to > have the preferred-package list stored somewhere so that we can use it for > new installations. I have wanted to have this functionality as well as I often copy my .emacs config around among multiple machines and would rather have a single step to pull in my set of preferred packages rather than getting them one by one. If it's agreed that we want it in package.el, I can give it a shot. -Phil ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 21:40 ` Phil Hagelberg @ 2010-08-28 17:34 ` Tom Tromey 0 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-28 17:34 UTC (permalink / raw To: Phil Hagelberg; +Cc: Uday S Reddy, emacs-devel >>>>> "Phil" == Phil Hagelberg <phil@hagelb.org> writes: Phil> I have wanted to have this functionality as well as I often copy Phil> my .emacs config around among multiple machines and would rather Phil> have a single step to pull in my set of preferred packages rather Phil> than getting them one by one. FWIW, you can just rsync ~/.emacs.d/elpa/. If you're already copying .emacs and whatever else, it isn't much more effort. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 1:43 ` Christoph ` (2 preceding siblings ...) 2010-08-26 23:27 ` Juri Linkov @ 2010-08-27 6:43 ` Uday S Reddy 2010-08-27 15:51 ` Tom Tromey ` (2 more replies) 3 siblings, 3 replies; 34+ messages in thread From: Uday S Reddy @ 2010-08-27 6:43 UTC (permalink / raw To: emacs-devel On 8/7/2010 2:43 AM, Christoph wrote: > I have a couple of thoughts: > I am wondering, is there a way to give package.el a list of packages to go > download from ELPA and install? I would also want it to use this list to check > for new versions of all packages in the list. Either on startup or on command > (M-x package-upgrade). Also, on a new installation of Emacs I would just tell > it "Go get the packages in the list" and it would recreate my package > configuration on that machine. All I need in version control is the list as > part of my init.el, instead of putting the entire elpa/ directory under version > control and deploying it to the new machine. I personally think that upgrading packages should be a conscious, deliberate action. You never know what changes the developers have put in the upgrade and what those change would entail in terms of how you will use the package. Many of the complaints we here from users about version changes stem from the fact that their distros or local admins do automatic updates. The users get burned as a result and take it out on us. Emacs obviously shouldn't encourage such irresponsible practices. You have to hit the button to make it happen. I will also want to install the new versions along side the old ones, so that I have the option of going back to the old versions if I need to. It is not yet clear to me if package.el allows that. Cheers, Uday ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 6:43 ` Uday S Reddy @ 2010-08-27 15:51 ` Tom Tromey 2010-08-27 16:17 ` Chong Yidong 2010-08-27 21:43 ` Richard Stallman 2 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-27 15:51 UTC (permalink / raw To: Uday S Reddy; +Cc: emacs-devel >>>>> "Uday" == Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes: Uday> I personally think that upgrading packages should be a conscious, Uday> deliberate action. You never know what changes the developers have Uday> put in the upgrade and what those change would entail in terms of how Uday> you will use the package. This is exactly why I didn't write package.el to work automatically :-) It should be implementable, though, if somebody really wants it. Another idea would be to do what Mozilla's plugin manager does: look for updates in the background, and notify the users of possible upgrades. Uday> I will also want to install the new versions along side the old ones, Uday> so that I have the option of going back to the old versions if I need Uday> to. It is not yet clear to me if package.el allows that. If you install a new version the old one will still be there. You have to explicitly delete it. So, you can go back to an older one by deleting the newer one. This isn't foolproof because installing a new version of a package may install new versions of its dependencies, and there's no easy way (without reading through files in ~/.emacs.d/elpa/) to know what those are after the fact. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 6:43 ` Uday S Reddy 2010-08-27 15:51 ` Tom Tromey @ 2010-08-27 16:17 ` Chong Yidong 2010-08-27 21:43 ` Richard Stallman 2 siblings, 0 replies; 34+ messages in thread From: Chong Yidong @ 2010-08-27 16:17 UTC (permalink / raw To: Uday S Reddy; +Cc: emacs-devel Uday S Reddy <u.s.reddy@cs.bham.ac.uk> writes: > I will also want to install the new versions along side the old ones, > so that I have the option of going back to the old versions if I need > to. It is not yet clear to me if package.el allows that. See `package-load-list'. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 6:43 ` Uday S Reddy 2010-08-27 15:51 ` Tom Tromey 2010-08-27 16:17 ` Chong Yidong @ 2010-08-27 21:43 ` Richard Stallman 2010-08-27 22:58 ` Christoph 2 siblings, 1 reply; 34+ messages in thread From: Richard Stallman @ 2010-08-27 21:43 UTC (permalink / raw To: Uday S Reddy; +Cc: emacs-devel I personally think that upgrading packages should be a conscious, deliberate action. You never know what changes the developers have put in the upgrade and what those change would entail in terms of how you will use the package. I agree. Not only that, but we want users to be conscious of and control what software they run. Leading them to let things be updated automatically is the opposite of that. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 21:43 ` Richard Stallman @ 2010-08-27 22:58 ` Christoph 2010-08-28 7:25 ` Uday S Reddy 0 siblings, 1 reply; 34+ messages in thread From: Christoph @ 2010-08-27 22:58 UTC (permalink / raw To: emacs-devel; +Cc: u.s.reddy, rms On 8/27/2010 3:43 PM, Richard Stallman wrote: > I personally think that upgrading packages should be a conscious, deliberate > action. You never know what changes the developers have put in the upgrade and > what those change would entail in terms of how you will use the package. > > I agree. Not only that, but we want users to be conscious of and control > what software they run. Leading them to let things be updated automatically > is the opposite of that. Agreed, but like Tom said, there could (and imho should) be an option to check for updates of specified packages on startup or periodically and provide an "update available" notification to the user. Options could be - Check manually - Check on startup - Check in a user-specified interval (once per day, week, month) - Check on startup and periodically If updates are available, a list of packages with updates should be presented to the user, where he can mark the packages he would like to upgrade. On a new installation this would also work and result in the latest version of all specified packages being installed. With user confirmation of course. That's what I was initially looking for. Christoph ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-27 22:58 ` Christoph @ 2010-08-28 7:25 ` Uday S Reddy 0 siblings, 0 replies; 34+ messages in thread From: Uday S Reddy @ 2010-08-28 7:25 UTC (permalink / raw To: emacs-devel On 8/27/2010 11:58 PM, Christoph wrote: > Agreed, but like Tom said, there could (and imho should) be an option to check > for updates of specified packages on startup or periodically and provide an > "update available" notification to the user. Right, you want a biff that says "you've got updates!" There are always a bunch of early adopter users who want the latest and the greatest versions. Such users are valuable for us because they provide quick feedback, initial bug reports etc. before the stuff gets more widely used. So, I would support adding a feature that will help them know when new updates are available. Cheers, Uday ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 22:42 document package.el Tom Tromey 2010-08-06 23:48 ` Phil Hagelberg 2010-08-07 1:43 ` Christoph @ 2010-08-07 7:47 ` Eli Zaretskii 2010-08-08 22:39 ` Chong Yidong 2010-08-21 18:22 ` Tom Tromey 2010-08-08 23:06 ` Chong Yidong 2010-08-17 14:37 ` Uday S Reddy 4 siblings, 2 replies; 34+ messages in thread From: Eli Zaretskii @ 2010-08-07 7:47 UTC (permalink / raw To: Tom Tromey; +Cc: emacs-devel > From: Tom Tromey <tromey@redhat.com> > Date: Fri, 06 Aug 2010 16:42:54 -0600 > > I'd appreciate comments on this patch. > > I finally found a little time to write some documentation for > package.el. Thanks. I never used package.el, so I can only comment on the clarity of the text and the correctness of Texinfo usage. Where I talk about functionality, it's based on ignorance rather than on anything else. > +@setfilename ../../info/os I guess you meant ../../info/package. These lines in lispref sources are actually obsolete: they seem to be for some use-case of compiling each source file independently outside of the main manual file elisp.texi. I don't see a need for this use-case, but as long as we keep those lines, we might as well make them consistent -- each one of them names the basename of the source file. > +@node Packaging, Antinews, System Interface, Top > +@chapter Preparing Lisp code for distribution It is a good idea to have a @cindex entry at the beginning of each chapter/section/subsection whose text is the name of the node, or some variant thereof. E.g., "@cindex packaging" here. > +uninstall, and upgrade Lisp code that they might want to use. Perhaps qualify "Lisp code" by "unbundled", because the bundled ones are supposed to be upgraded by installing a newer Emacs version. > +Lisp code, but it is possible to create other kinds of packages as > +well, for example, a package consisting solely of documentation. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Which somewhat contradicts what you said above ("upgrade Lisp code"). > +@node Packaging Basics > +@section Packaging Basics Same comment as above about a @cindex entry. (Same goes for all the other sections.) > + A package has a few attributes: Suggest a "@cindex package attributes" here. > +@item Version > +A version number, which is a dotted list of integers, like > +@samp{1.2.0.3}. Only integers? Emacs supports more flexible version strings, see subr.el. > +@item Manual > +A package can include an info manual. "Info", with a capital I (here and elsewhere). > + Conceptually, a package goes through several state transitions (in Suggest a "@cindex package states" here. > +@item Install > +Untar the package, or write a @file{.el} file into the appropriate Suggest to use "unpack", which is more neutral to the archive format. > +activation time. The best approach is to have activation consist of a > +some autoloads and little more. ^^ That "a" should be removed. > + The simplest package consists of a single Emacs Lisp source file. > +In this case, all the attributes of the package are taken from this > +file. It would be good to have a cross-reference to where the attributes are described after "all the attributes of the package". In general, do not assume that the reader is going through the documentation in order. She could have gotten here by following some @xref, and therefore does not necessarily remembers what are the attributes, because she could have read about them a long time ago, maybe not at all. > +Emacs Lisp library header conventions. See @xref{Library Headers}. @xref produces the "See" part automatically, so either remove "See" or use "See @ref". > + The name of the package is the same as the base name of the > +@file{.el} file, as written in the first comment line. This made me wonder whether package.el will fall back to the file's name itself, if that first comment line is absent or malformed. Perhaps the docs should cover what happens in that case (for every attribute), even if just by saying that the corresponding attribute will be displayed as empty. > + A package is > +required to have a version number. And if it doesn't? > + The file will be scanned for autoload comments at install time. At this point I wondered why nothing is done with the Author and Maintainer headers. > + A multi-file package is just a @file{.tar} file. Does package.el really support only .tar files? That sounds like an unnecessary limitation, since Emacs supports much more. > + The contents of the @file{.tar} file must all appear in a single > +directory, named after the package and version. Are subdirectories allowed? If yes, I suggest to mention that. If no, it again sounds like a limitation that perhaps should be lifted. > + If a @file{README} file exists in the content directory, then it is > +used as the long description. If this means a multi-file package cannot have a long description in the form of "Commentary", then this sounds like an inconvenience, e.g., if a package starts as a single file and then develops into a multi-file one. > + If the package has an info manual, you should distribute the needed > +info files, plus a @file{dir} file made with @command{install-info}. Not clear why the `dir' file is needed. Are you trying to support users that don't have install-info on their systems? > + The installation process will scan all the @file{.el} files in the > +package for autoload comments. I believe the rest of the Emacs documentation calls them "autoload cookies". Also, a cross reference to the "Autoloads" node would be good here. > +@item Package-Version > +If @samp{Version} is not suitable for use by the package manager, then > +a package can define @samp{Package-Version}; it will be used instead. > +This is handy if @samp{Version} is an RCS id or something else that is > +not a dotted list of integers. A cross-reference here to the appropriate node of package.texi would be a good idea. In general, this section should have some verbiage explaining how package.el comes into play and pointing to package.texi, because otherwise text like the following one is a big surprise: > +@item Package-Requires > +If this exists, it names packages on which the current package > +depends for proper operation. This is used by the package manager > +both at download time (to ensure that a complete set of packages is > +downloaded) and at activation time (to ensure that a package is > +activated if and only if all its dependencies have been). "Package manager"? "download time"? "activation time"? these are explained in package.texi, but the reader of this section is not necessarily aware of that feature. > +The package code automatically defines a package named @samp{eamcs} ^^^^^ A typo. > +with the version number of the currently running Emacs. This can be > +used to require a minimal version of Emacs for a package. I wonder if this text and the preceding example should be copied (or moved?) into package.texi, and this node just have an @xref pointing there. Thanks again for working on this. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 7:47 ` Eli Zaretskii @ 2010-08-08 22:39 ` Chong Yidong 2010-08-09 16:24 ` Tom Tromey 2010-08-21 18:22 ` Tom Tromey 1 sibling, 1 reply; 34+ messages in thread From: Chong Yidong @ 2010-08-08 22:39 UTC (permalink / raw To: Eli Zaretskii; +Cc: Tom Tromey, emacs-devel Eli Zaretskii <eliz@gnu.org> writes: >> +@item Version >> +A version number, which is a dotted list of integers, like >> +@samp{1.2.0.3}. > > Only integers? Emacs supports more flexible version strings, see > subr.el. Oh yeah, I had forgotten about that. The parts of package.el that deal with version numbers probably ought to use `version-to-list', `version-list-<', etc. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-08 22:39 ` Chong Yidong @ 2010-08-09 16:24 ` Tom Tromey 0 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-09 16:24 UTC (permalink / raw To: Chong Yidong; +Cc: Eli Zaretskii, emacs-devel >>>>> "Chong" == Chong Yidong <cyd@stupidchicken.com> writes: Chong> Oh yeah, I had forgotten about that. The parts of package.el that deal Chong> with version numbers probably ought to use `version-to-list', Chong> `version-list-<', etc. Yeah. I actually took a quick look at this while writing the docs, but some places in package.el reconstruct the version string from the split version, so it looked like a change that would take more time than I have. I'm supportive if somebody else wants to take a stab at this. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-07 7:47 ` Eli Zaretskii 2010-08-08 22:39 ` Chong Yidong @ 2010-08-21 18:22 ` Tom Tromey 2010-08-21 18:51 ` Eli Zaretskii 1 sibling, 1 reply; 34+ messages in thread From: Tom Tromey @ 2010-08-21 18:22 UTC (permalink / raw To: Eli Zaretskii; +Cc: emacs-devel >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes: Tom> I finally found a little time to write some documentation for Tom> package.el. [...] Eli> At this point I wondered why nothing is done with the Author and Eli> Maintainer headers. They weren't needed by the package manager. Tom> + A multi-file package is just a @file{.tar} file. Eli> Does package.el really support only .tar files? That sounds like an Eli> unnecessary limitation, since Emacs supports much more. Emacs doesn't have built-in support for anything else. It relies on external programs. Since I think it is best not to rely on the environment this way, I purposely limited package.el. I still think this was a good decision, because it only affects packagers, not users. I don't know of any gain to be had by expanding this. In any case I wrote the documentation to describe what exists now. Eli> If this means a multi-file package cannot have a long description in Eli> the form of "Commentary", then this sounds like an inconvenience, Eli> e.g., if a package starts as a single file and then develops into a Eli> multi-file one. The problem is knowing which file to extract this information from. It is not uncommon for several files to have comment headers. Tom> + If the package has an info manual, you should distribute the needed Tom> +info files, plus a @file{dir} file made with @command{install-info}. Eli> Not clear why the `dir' file is needed. Are you trying to support Eli> users that don't have install-info on their systems? Yes. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-21 18:22 ` Tom Tromey @ 2010-08-21 18:51 ` Eli Zaretskii 2010-08-22 1:40 ` Tom Tromey 0 siblings, 1 reply; 34+ messages in thread From: Eli Zaretskii @ 2010-08-21 18:51 UTC (permalink / raw To: Tom Tromey; +Cc: emacs-devel > From: Tom Tromey <tromey@redhat.com> > Date: Sat, 21 Aug 2010 12:22:56 -0600 > Cc: emacs-devel@gnu.org > > Eli> Does package.el really support only .tar files? That sounds like an > Eli> unnecessary limitation, since Emacs supports much more. > > Emacs doesn't have built-in support for anything else. It relies on > external programs. Since I think it is best not to rely on the > environment this way, I purposely limited package.el. Most environments that have Emacs also have the external programs needed for the other formats. The difference between a hard limitation and a soft one (which is in effect only if the required program is not available) is that in the former case the user doesn't have any choice (except to hack package.el), while in the latter she can install the missing program and be done. > I still think this was a good decision, because it only affects > packagers, not users. "Only packagers"? What about a package I downloaded from elsewhere? I don't expect many packages nowadays to come in a .tar format. > Tom> + If the package has an info manual, you should distribute the needed > Tom> +info files, plus a @file{dir} file made with @command{install-info}. > > Eli> Not clear why the `dir' file is needed. Are you trying to support > Eli> users that don't have install-info on their systems? > > Yes. Why? ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-21 18:51 ` Eli Zaretskii @ 2010-08-22 1:40 ` Tom Tromey 0 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-22 1:40 UTC (permalink / raw To: Eli Zaretskii; +Cc: emacs-devel >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes: Eli> Most environments that have Emacs also have the external programs Eli> needed for the other formats. ... but some don't. Eli> "Only packagers"? What about a package I downloaded from elsewhere? Eli> I don't expect many packages nowadays to come in a .tar format. I don't know what packages you could possibly mean. Packages for use with package.el must be packaged according to the rules imposed by package.el. Of these rules, use of .tar is a trivial one, the other impose a lot more burden. Users of package.el generally install packages from the package archive, via the package menu mode. They don't generally just download random .tar files. And, if they did -- so what? The .tar is just the distribution format. Tom> + If the package has an info manual, you should distribute the needed Tom> +info files, plus a @file{dir} file made with @command{install-info}. Eli> Not clear why the `dir' file is needed. Are you trying to support Eli> users that don't have install-info on their systems? Tom> Yes. Eli> Why? My goal in writing package.el was a seamless user experience. I tried hard to minimize the number of error modes that a user could see. Hence: * Use of .tar and not anything else, even .tar.gz -- because .tar can be unpacked entirely in elisp. * Use of package dependencies, to make it so you can't install a package and have it not work. * Before I upload a package I also generally make a point of looking at how it is activated, looking at least for autoload cookies. The general theme is to make packagers do a bit more work so that users get a better experience. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 22:42 document package.el Tom Tromey ` (2 preceding siblings ...) 2010-08-07 7:47 ` Eli Zaretskii @ 2010-08-08 23:06 ` Chong Yidong 2010-08-09 21:13 ` Tom Tromey 2010-08-21 18:37 ` Tom Tromey 2010-08-17 14:37 ` Uday S Reddy 4 siblings, 2 replies; 34+ messages in thread From: Chong Yidong @ 2010-08-08 23:06 UTC (permalink / raw To: Tom Tromey; +Cc: Emacs discussions Tom Tromey <tromey@redhat.com> writes: > + A @dfn{package} is simply one or more files, formatted and bundled > +in a particular way. Typically a package includes primarily Emacs > +Lisp code, but it is possible to create other kinds of packages as > +well, for example, a package consisting solely of documentation. I don't think the documentation-only use case is important to mention. Just say that you can include stuff other than Emacs Lisp code, such as Info files. > +This is shown to the user in the package menu buffer. It is just a > +single line. We should probably recommend a stronger length limit. By default, there are only 36 characters in the package buffer. > +Emacs Lisp library header conventions. See @xref{Library Headers}. Omit the "See", as it would produce "See see Library Headers". > + The name of the package is the same as the base name of the > +@file{.el} file, as written in the first comment line. Give an example here. > + A multi-file package is just a @file{.tar} file. BTW, this is off-topic, but I've been meaning to ask why you don't use .tar.gz files. Is the bandwidth difference insignificant? > +@file{superfrobnicator-pkg.el}. This file must have a single form in > +it, a call to @code{define-package}. The package dependencies and You should add a @defun for `define-package'. > +@item Package-Version > ... > +@item Package-Requires In these list items, you should add xrefs to the packaging node. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-08 23:06 ` Chong Yidong @ 2010-08-09 21:13 ` Tom Tromey 2010-08-21 18:37 ` Tom Tromey 1 sibling, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-09 21:13 UTC (permalink / raw To: Chong Yidong; +Cc: Emacs discussions >>>>> "Chong" == Chong Yidong <cyd@stupidchicken.com> writes: I'll reply to the rest of the patch reviews later, whenever I can get some time to update the patch. Tom> + A multi-file package is just a @file{.tar} file. Chong> BTW, this is off-topic, but I've been meaning to ask why you don't use Chong> .tar.gz files. Is the bandwidth difference insignificant? I haven't tried to measure it. I wanted to have minimal dependencies on the user's side, so I didn't want to rely on a decompressor. With a recent enough Emacs, you don't even need a 'tar' program, due to tar-untar-buffer. Some sort of optional compression would be fine. It seems like this could be handled transparently by the URL package, though, in conjunction with a server that knew how to serve compressed files automatically. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-08 23:06 ` Chong Yidong 2010-08-09 21:13 ` Tom Tromey @ 2010-08-21 18:37 ` Tom Tromey 2010-08-25 17:24 ` Chong Yidong 1 sibling, 1 reply; 34+ messages in thread From: Tom Tromey @ 2010-08-21 18:37 UTC (permalink / raw To: Chong Yidong; +Cc: Emacs discussions Here is an updated version of my proposed package.el documentation. I have tried to address all the comments. Tom === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2010-08-20 20:07:29 +0000 +++ doc/lispref/ChangeLog 2010-08-21 18:26:54 +0000 @@ -1,3 +1,14 @@ +2010-08-21 Tom Tromey <tromey@redhat.com> + + * vol2.texi (Top): Update. + * vol1.texi (Top): Update. + * tips.texi (Library Headers): Mention Package-Version and + Package-Requires. + * package.texi: New file. + * os.texi (System Interface): Update pointers. + * elisp.texi (Top): Link to new nodes. Include package.texi. + * anti.texi (Antinews): Update pointers. + 2010-08-20 Eli Zaretskii <eliz@gnu.org> * commands.texi (Misc Events): Add cross-references to where === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2010-01-13 08:35:10 +0000 +++ doc/lispref/anti.texi 2010-07-30 00:05:33 +0000 @@ -6,7 +6,7 @@ @c This node must have no pointers. -@node Antinews, GNU Free Documentation License, System Interface, Top +@node Antinews, GNU Free Documentation License, Packaging, Top @appendix Emacs 22 Antinews @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries @c with the above version number. === modified file 'doc/lispref/elisp.texi' --- doc/lispref/elisp.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/elisp.texi 2010-07-31 01:32:13 +0000 @@ -159,6 +159,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1394,6 +1396,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. @@ -1490,6 +1498,8 @@ @include display.texi @include os.texi +@include package.texi + @c MOVE to Emacs Manual: include misc-modes.texi @c appendices === modified file 'doc/lispref/os.texi' --- doc/lispref/os.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/os.texi 2010-07-30 00:05:24 +0000 @@ -5,7 +5,7 @@ @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/os -@node System Interface, Antinews, Display, Top +@node System Interface, Packaging, Display, Top @chapter Operating System Interface This chapter is about starting and getting out of Emacs, access to === added file 'doc/lispref/package.texi' --- doc/lispref/package.texi 1970-01-01 00:00:00 +0000 +++ doc/lispref/package.texi 2010-08-21 18:35:39 +0000 @@ -0,0 +1,189 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2010 +@c Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/package +@node Packaging, Antinews, System Interface, Top +@chapter Preparing Lisp code for distribution +@cindex packaging + + Emacs provides a standard way for Emacs Lisp code to be distributed +to users. This approach lets users easily download, install, +uninstall, and upgrade Lisp code that they might want to use. + + A @dfn{package} is simply one or more files, formatted and bundled +in a particular way. Typically a package includes primarily Emacs +Lisp code, but it is possible to create other kinds of packages as +well. + +@menu +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. +@end menu + +@node Packaging Basics +@section Packaging Basics +@cindex packaging basics + + A package has a few attributes: +@cindex package attributes + +@table @asis +@item Name +A string, the name of the package. This attribute is mandatory. If +it does not exist, the package cannot be installed by the package +manager. + +@item Version +A version number, which is anything that can be parsed by +@code{version-to-list}. This attribute is mandatory. If it does not +exist, the package cannot be installed by the package manager. + +@item Brief description +This is shown to the user in the package menu buffer. It is just a +single line. On a terminal with 80 characters per line, there are +only 36 characters available in the package menu mode for showing the +brief description, so it is best to keep it very brief. If no brief +name is given, an empty string is used. + +@item Long description +This can be a @file{README} file or the like. This is available to +the user before the package is installed, via the package menu. It +should more fully describe the package and its capabilities, so a user +can read it to decide whether he wants to install the package. This +attribute is optional. + +@item Dependencies +This is a list of other packages and their minimal acceptable +versions. This is used both at download time (to make sure all the +needed code is available) and at activation time (to ensure a package +is only activated if all its dependencies have been successfully +activated). This attribute is optional. + +@item Manual +A package can optionally include an Info manual. +@end table + + Conceptually, a package goes through several state transitions (in +reality some of these transitions are grouped together): + +@table @asis +@item Download +Fetch the package from somewhere. + +@item Install +Unpack the package, or write a @file{.el} file into the appropriate +install directory. This step also includes extracting autoloads and +byte-compiling the Emacs Lisp code. + +@item Activate +Update @code{load-path} and @code{Info-directory-list} and evaluate +the autoloads, so that the package is ready for the user to use. +@end table + + It is best for users if packages do not do too much work at +activation time. The best approach is to have activation consist of +some autoloads and little more. + +@node Simple Packages +@section Simple Packages +@cindex single file packages + + The simplest package consists of a single Emacs Lisp source file. +In this case, all the attributes of the package (@pxref{Packaging +Basics}) are taken from this file. + + The package system expects this @file{.el} file to conform to the +Emacs Lisp library header conventions. @xref{Library Headers}. + + The name of the package is the same as the base name of the +@file{.el} file, as written in the first comment line. For example, +given the header line: + +@smallexample +;;; superfrobnicator.el --- frobnicate and bifurcate flanges +@end smallexample + +the package name will be @samp{superfrobnicator}. + + The short description of the package is also taken from the first +line of the file. + + If the file has a ``Commentary'' header, then it is used as the long +description. + + The version of the package comes either from the ``Package-Version'' +header, if it exists, or from the ``Version'' header. A package is +required to have a version number. Each release of a package must be +accompanied by an increase in the version number. + + If the file has a ``Package-Requires'' header, then that is used as +the package dependencies. Otherwise, the package is assumed not to +have any dependencies. + + A single-file package cannot have an Info manual. + + The file will be scanned for autoload cookies at install time. +@xref{Autoload}. + +@node Multi-file Packages +@section Multi-file Packages +@cindex multi-file packages + + A multi-file package is just a @file{.tar} file. While less +convenient to create than a single-file package, a multi-file package +also offers more features: it can include an Info manual, multiple +Emacs Lisp files, and also other data files needed by a package. + + The contents of the @file{.tar} file must all appear beneath a +single directory, named after the package and version. Files can +appear in subdirectories of this top-most directory, but Emacs Lisp +code will only be found (and thus byte-compiled) at the top-most +level. Also, the @file{.tar} file is typically also given this same +name. For example, if you are distributing version 1.3 of the +superfrobnicator, the package file would be named +``superfrobnicator-1.3.tar'' and the contents would all appear in the +directory @file{superfrobnicator-1.3} in that @file{.tar}. + + The package must include a @file{-pkg.el} file, named after the +package. In our example above, this file would be called +@file{superfrobnicator-pkg.el}. This file must have a single form in +it, a call to @code{define-package}. The package dependencies and +brief description are taken from this form. + +@defun define-package name version &optional docstring requirements +Define a package. @var{name} is the name of the package, a string. +@var{version} is the package's version, a string. It must be in a +form that can be understood by @code{version-to-list}. +@var{docstring} is the short description of the package. +@var{requirements} is a list of required packages and their versions. +@end defun + + If a @file{README} file exists in the content directory, then it is +used as the long description. + + If the package has an Info manual, you should distribute the needed +info files, plus a @file{dir} file made with @command{install-info}. +@xref{Invoking install-info, Invoking install-info, Invoking +install-info, texinfo, Texinfo}. + + Do not include any @file{.elc} files in the package. Those will be +created at install time. Note that there is no way to control the +order in which files are byte-compiled; your package must be robust +here. + + The installation process will scan all the @file{.el} files in the +package for autoload cookies. @xref{Autoload}. They are extracted +into a @file{-autoloads.el} file (e.g., +@file{superfrobnicator-autoloads.el}), so do not include a file of +that name in your package. + + Any other files in the @file{.tar} file are simply unpacked when the +package is installed. This can be useful if your package needs +auxiliary data files --- e.g., icons or sounds. + + Emacs Lisp code installed via the package manager must take special +care to the location-independent. One easy way to do this is to make +references to auxiliary data files relative to @var{load-file-name}. === modified file 'doc/lispref/tips.texi' --- doc/lispref/tips.texi 2010-06-23 03:36:56 +0000 +++ doc/lispref/tips.texi 2010-08-21 18:17:25 +0000 @@ -1052,6 +1052,31 @@ This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both. + +@item Package-Version +If @samp{Version} is not suitable for use by the package manager, then +a package can define @samp{Package-Version}; it will be used instead. +This is handy if @samp{Version} is an RCS id or something else that +cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}. + +@item Package-Requires +If this exists, it names packages on which the current package depends +for proper operation. @xref{Packaging Basics}. This is used by the +package manager both at download time (to ensure that a complete set +of packages is downloaded) and at activation time (to ensure that a +package is activated if and only if all its dependencies have been). + +Its format is a list of lists. The @code{car} of each sub-list is the +name of a package, as a symbol. The @code{cadr} of each sub-list is +the minimum acceptable version number, as a string. For instance: + +@smallexample +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +@end smallexample + +The package code automatically defines a package named @samp{emacs} +with the version number of the currently running Emacs. This can be +used to require a minimal version of Emacs for a package. @end table Just about every Lisp library ought to have the @samp{Author} and === modified file 'doc/lispref/vol1.texi' --- doc/lispref/vol1.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol1.texi 2010-07-31 01:32:31 +0000 @@ -180,6 +180,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1415,6 +1417,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. === modified file 'doc/lispref/vol2.texi' --- doc/lispref/vol2.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol2.texi 2010-07-31 01:32:50 +0000 @@ -179,6 +179,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1414,6 +1416,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-21 18:37 ` Tom Tromey @ 2010-08-25 17:24 ` Chong Yidong 2010-08-25 17:34 ` Tom Tromey 0 siblings, 1 reply; 34+ messages in thread From: Chong Yidong @ 2010-08-25 17:24 UTC (permalink / raw To: Tom Tromey; +Cc: Emacs discussions Tom Tromey <tromey@redhat.com> writes: > + Emacs Lisp code installed via the package manager must take special > +care to the location-independent. One easy way to do this is to make ^^^ Typo here. Other that this, I see no problems with the patch, so go ahead and install whenever you like. It would be nice if you could write a more detailed explanation of how to determine the pathname of non-Lisp files, such as images, that are included with the package. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-25 17:24 ` Chong Yidong @ 2010-08-25 17:34 ` Tom Tromey 2010-08-25 17:35 ` Chong Yidong 0 siblings, 1 reply; 34+ messages in thread From: Tom Tromey @ 2010-08-25 17:34 UTC (permalink / raw To: Chong Yidong; +Cc: Emacs discussions Chong> It would be nice if you could write a more detailed explanation of how Chong> to determine the pathname of non-Lisp files, such as images, that are Chong> included with the package. What do you think of this addition? For example: @smallexample (defconst superfrobnicator-base (file-name-directory load-file-name)) (defun superfrobnicator-fetch-image (file) (expand-file-name file superfrobnicator-base)) @end smallexample Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-25 17:34 ` Tom Tromey @ 2010-08-25 17:35 ` Chong Yidong 0 siblings, 0 replies; 34+ messages in thread From: Chong Yidong @ 2010-08-25 17:35 UTC (permalink / raw To: Tom Tromey; +Cc: Emacs discussions Tom Tromey <tromey@redhat.com> writes: > What do you think of this addition? > > For example: > > @smallexample > (defconst superfrobnicator-base (file-name-directory load-file-name)) > > (defun superfrobnicator-fetch-image (file) > (expand-file-name file superfrobnicator-base)) > @end smallexample Looks good. ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-06 22:42 document package.el Tom Tromey ` (3 preceding siblings ...) 2010-08-08 23:06 ` Chong Yidong @ 2010-08-17 14:37 ` Uday S Reddy 2010-08-17 15:57 ` Tom Tromey 4 siblings, 1 reply; 34+ messages in thread From: Uday S Reddy @ 2010-08-17 14:37 UTC (permalink / raw To: emacs-devel Tom Tromey wrote: > I'd appreciate comments on this patch. > > I finally found a little time to write some documentation for > package.el. Dear Tom, thanks for providing this info page. Very much appreciated! The document doesn't seem to mention where the package will be installed or how to customize the location. Is that intentional? Does package.el handle only elisp files or other kinds of files as well? Where will the other files be installed? Sorry if all this has been covered before. I am still trying to catch up on the old discussin. Cheers, Uday ^ permalink raw reply [flat|nested] 34+ messages in thread
* Re: document package.el 2010-08-17 14:37 ` Uday S Reddy @ 2010-08-17 15:57 ` Tom Tromey 0 siblings, 0 replies; 34+ messages in thread From: Tom Tromey @ 2010-08-17 15:57 UTC (permalink / raw To: Uday S Reddy; +Cc: emacs-devel Uday> The document doesn't seem to mention where the package will be Uday> installed or how to customize the location. Is that intentional? This particular documentation is just for package authors. Customizations would be described in the user documentation instead. Uday> Does package.el handle only elisp files or other kinds of files as Uday> well? Where will the other files be installed? Yes, anything in the appropriate directory in the .tar is unpacked. You can ship anything you like in your package -- some existing packages ship data files that they need. Perhaps the docs should mention that elisp installed this way ought to be location-independent. Tom ^ permalink raw reply [flat|nested] 34+ messages in thread
end of thread, other threads:[~2010-08-28 17:34 UTC | newest] Thread overview: 34+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-08-06 22:42 document package.el Tom Tromey 2010-08-06 23:48 ` Phil Hagelberg 2010-08-09 16:22 ` Tom Tromey 2010-08-07 1:43 ` Christoph 2010-08-07 8:57 ` Geralt 2010-08-09 16:23 ` Tom Tromey 2010-08-26 23:27 ` Juri Linkov 2010-08-26 23:50 ` Stefan Monnier 2010-08-27 3:14 ` Christoph 2010-08-27 5:51 ` Uday S Reddy 2010-08-27 3:12 ` Christoph 2010-08-27 7:07 ` Uday S Reddy 2010-08-27 21:40 ` Phil Hagelberg 2010-08-28 17:34 ` Tom Tromey 2010-08-27 6:43 ` Uday S Reddy 2010-08-27 15:51 ` Tom Tromey 2010-08-27 16:17 ` Chong Yidong 2010-08-27 21:43 ` Richard Stallman 2010-08-27 22:58 ` Christoph 2010-08-28 7:25 ` Uday S Reddy 2010-08-07 7:47 ` Eli Zaretskii 2010-08-08 22:39 ` Chong Yidong 2010-08-09 16:24 ` Tom Tromey 2010-08-21 18:22 ` Tom Tromey 2010-08-21 18:51 ` Eli Zaretskii 2010-08-22 1:40 ` Tom Tromey 2010-08-08 23:06 ` Chong Yidong 2010-08-09 21:13 ` Tom Tromey 2010-08-21 18:37 ` Tom Tromey 2010-08-25 17:24 ` Chong Yidong 2010-08-25 17:34 ` Tom Tromey 2010-08-25 17:35 ` Chong Yidong 2010-08-17 14:37 ` Uday S Reddy 2010-08-17 15:57 ` Tom Tromey
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.