box.matto.nl
Enjoying Open Source Software

Posted:

Lessons learned from creating my first ELPA package

Everything I wish I knew before creating a package

Recently Philip Kaludercic helped me in developing an Emacs package, to be distributed as an ELPA package.

This was a wonderful experience, from which I learned a lot.

Philip very patiently guided me, explaining things, showing which way to go, and helping me out when I hit a wall.

During the process I made discoveries that may seem trivial to experienced Elisp-ers, but can be beneficial to those who are new to the subject.

Now that the experience is still fresh, I'd want to jot down some points that may be useful for others creating ELPA packages.

Copyright Assignment

Working on GNU software requires that you first sign the copyright assignment. This includes non-trivial patches for e.g,, Emacs, A signed copyright assignment is also required for packages to be added to ELPA.

For NonGNU ELPA a copyright assignment is not required.

See Copyright assignment with the FSF,

Auto-insert

Emacs is there to help you!

Don't start an Elisp file from scratch, but use the magic of auto-insert:

  • Open a new file with the .el extension.
  • Run M-x auto-insert

This will interactively start up your Elisp file.

Next, start your documentation file:

  • Open a new file with the .texi extension.
  • Run M-x auto-insert

This will interactively start up your Texinfo file.

Flymake-mode

After you have created the Elisp file with auto-insert, there are some other parts to add:

  • ;;; Commentary: description of what your package does
  • ;;; Code: end of the preamble and start of your code
  • (provide <packagename>) and <filename.el> end here: footer of your Elisp file

This, and many other customary elements in your code, like the contents of the document strings in your functions, are checked by Flymake.

All you have to do is to start flymake-mode with M-x flymake-mode, and open the buffer with the Flymake diagnostics.

The easiest way to do that, is M-x flymake-show-buffer-diagnostics.

Another way is to open the menu with F10 and go to the Flymake menu, or use your mouse. Next, select "List all problems".

Besides using a buffer to show the diagnostics, Flymake offers another options. Either use C-h . or set flymake-show-diagnostics-at-end-of-line.

Use Flymake not only for Elisp code, but also for Texinfo files.

Make it a habit to regularly consult the Flymake diagnostics while developing your code.

Flymake is a built-in package in Emacs. See the friendly Flymake manual.

Locally build your package

Locally install the ELPA tar-ball builder, and check that your packages can be build without problems.

Set up the environment:

apt-get install bubblewrap imagemagick
git clone --single-branch https://git.sv.gnu.org/git/emacs/elpa.git
cd elpa
make

Now, in the directory packages create a subcategory with your package. The result should be something like this:

elpa
├── packages
│   └── your-package-name
│       ├── fdl.texi
│       ├── LICENSE
│       ├── your-package.el
│       ├── your-package.texi
│       └── README.org

From the elpa directory, issue the commands:

make packages/your-package-name
make build packages/your-package-name

And resolve any issue that comes up.

See the README files in the admin directory.

Note: The apt-get install line above contains just the packages that I had to add. Packages needed to build Emacs from source where already on this system. Perhaps in your situation you have to install additional packages.

Create a public Git repository

There are many Git hosting providers where you can set up a public Git repository. Select one that fits your preferences, create a repository and push your package to it.

Emacs developers list

Subscribe to the Emacs developers list emacs-devel@gnu.org.

There you can kindly propose your package to be added to ELPA.

Reflection

I learned a lot from developing the package.

Before undertaking this project, I have done a little bit of Elisp programming, totaling to around two thousand lines of code, all for personal use.

Throughout the process, Philip provided feedback on my code and code suggestions. This was very beneficial and advanced my skills at an unanticipated rate.

I had to become familiar with Emacs/Elisp internals, like tabulated-list-mode, advice-add, advise-remove, completion-read, mode-line-buffer-identification and more.

I really enjoy coding in Elisp.

Tags:

⇽ Small Gopher HOW-TO Twentysix year old RedHat 5.2 on QEMU i386 ⇾