Difference between revisions of "Lisp package guidelines"

From ArchWiki
Jump to: navigation, search
m (ASDF)
m (corrected wikipedia link of Lisp)
(8 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:Package development (English)]]
+
[[Category:Package development]]
[[Category:Guidelines (English)]]
+
[[it:Lisp Package Guidelines]]
== Background ==
+
{{Package Guidelines}}
  
At the moment, there are relatively few lisp packages available in the
+
At the moment, there are relatively few [[Wikipedia:Lisp_(programming_language)|Lisp]] packages available in the Arch repositories. This means that at some point or another, more will likely appear. It is useful, therefore, to figure out now, while there are few packages, how they should be packaged.
Arch repositories. This means that at some point or another, more will
+
likely appear. It is useful, therefore, to figure out now, while there
+
are few packages, how they should be packaged. Therefore, this page
+
stands as a proposed packaging guideline for lisp packages. Keep in
+
mind, however, that this is a work in progress; if you disagree with
+
some of the ideas suggested here, feel free to edit the page and
+
propose something better.
+
  
 
== Directory Structure and Naming ==
 
== Directory Structure and Naming ==
 
+
There is at least one package in the base repository ({{Pkg|libgpg-error}})
There is at least one package in the base repository (libgpg-error)
+
 
that includes lisp files, which are placed in
 
that includes lisp files, which are placed in
'''/usr/share/common-lisp/source/gpg-error'''. In keeping with this,
+
{{Ic|/usr/share/common-lisp/source/gpg-error}}. In keeping with this,
 
other lisp packages should also place their files in
 
other lisp packages should also place their files in
'''/usr/share/common-lisp/source/'''. Each package should have its own
+
{{Ic|/usr/share/common-lisp/source/''pkgname''}}.
directory, so as not to clutter up this base directory.
+
  
The package directory
+
The package directory should be the name of the lisp package, not what it's called in the [[Official Repositories|Arch repository]] (or [[AUR]]). This applies even to single-file packages.
should be the name of the lisp package, not what it's called in the
+
Arch repository (or AUR). This applies even to single-file packages.
+
  
For example, a Lisp package called '''cl-ppcre''' should be called
+
For example, a Lisp package called ''"cl-ppcre"'' should be called {{Ic|cl-ppcre}} in AUR and reside in {{Ic|/usr/share/common-lisp/source/'''cl-ppcre'''}}.
'''cl-ppcre''' in AUR and reside in '''/usr/share/common-lisp/source/cl-ppcre'''.
+
A Lisp package called ''"alexandria"'' should be called {{Ic|cl-alexandria}} in AUR and reside in {{Ic|/usr/share/common-lisp/source/'''alexandria'''}}.
A Lisp package called '''alexandria''' should be called '''cl-alexandria'''
+
in AUR and reside in '''/usr/share/common-lisp/source/alexandria'''.
+
  
 
== ASDF ==
 
== ASDF ==
 +
Try to avoid the usage of ASDF-Install as a means of installing these system-wide packages.
  
Try to avoid the usage of ASDF-Install as a means of installing these
+
ASDF itself may be necessary or helpful as a means of compiling and/or loading packages. In that case, it is suggested that the directory used for the central registry (the location of all of the symlinks to {{Ic|*.asd}}) be {{Ic|/usr/share/common-lisp/systems/}}.
system-wide packages.
+
  
ASDF itself may be necessary or helpful as a means of compiling and/or
+
However, I have observed problems with doing the compilation with asdf as a part of the package compilation process. However, it does work during an install, through use of a {{Ic|''package''.install}} file. Such a file might look like this:
loading packages. In that case, it is suggested that the directory
+
used for the central registry (the location of all of the symlinks
+
to *.asd) be '''/usr/share/common-lisp/systems/'''.
+
  
However, I have observed problems with doing the compilation with asdf
+
{{hc|cl-ppcre.install|<nowiki>
as a part of the package compilation process. However, it does work
+
# arg 1:  the new package version
during an install, through use of a package.install file. Such a file
+
post_install() {
might look like this:
+
    echo "---> Compiling lisp files <---"
  
# cl-ppcre.install
+
    clisp --silent -norc -x \
# arg 1:  the new package version
+
        "(load #p\"/usr/share/common-lisp/source/asdf/asdf\") \
post_install() {
+
        (pushnew #p\"/usr/share/common-lisp/systems/\" asdf:*central-registry* :test #'equal) \
    echo "---> Compiling lisp files <---"
+
        (asdf:operate 'asdf:compile-op 'cl-ppcre)"
+
    clisp --silent -norc -x \
+
        "(load #p\"/usr/share/common-lisp/source/asdf/asdf\") \
+
        (pushnew #p\"/usr/share/common-lisp/systems/\" asdf:*central-registry* :test #'equal) \
+
        (asdf:operate 'asdf:compile-op 'cl-ppcre)"
+
+
    echo "---> Done compiling lisp files <---"
+
+
    cat << EOM
+
+
    To load this library, load asdf and then place the following lines
+
    in your ~/.clisprc.lisp file:
+
+
    (push #p"/usr/share/common-lisp/systems/" asdf:*central-registry*)
+
    (asdf:operate 'asdf:load-op 'cl-ppcre)
+
EOM
+
}
+
+
post_upgrade() {
+
    post_install $1
+
}
+
+
pre_remove() {
+
    rm /usr/share/common-lisp/source/cl-ppcre/{*.fas,*.lib}
+
}
+
+
op=$1
+
shift
+
+
$op $*
+
  
Of course, for this example to work, there needs to be a symlink to
+
    echo "---> Done compiling lisp files <---"
package.asd in the asdf system directory. During package compilation,
+
 
a stanza such as this will do the trick...
+
    cat << EOM
 +
 
 +
    To load this library, load asdf and then place the following lines
 +
    in your ~/.clisprc.lisp file:
 +
 
 +
    (push #p"/usr/share/common-lisp/systems/" asdf:*central-registry*)
 +
    (asdf:operate 'asdf:load-op 'cl-ppcre)
 +
EOM
 +
}
 +
 
 +
post_upgrade() {
 +
    post_install $1
 +
}
 +
 
 +
pre_remove() {
 +
    rm /usr/share/common-lisp/source/cl-ppcre/{*.fas,*.lib}
 +
}
 +
 
 +
op=$1
 +
shift
 +
 
 +
$op $*
 +
</nowiki>}}
 +
Of course, for this example to work, there needs to be a symlink to package.asd in the asdf system directory. During package compilation, a stanza such as this will do the trick...
  
 
  pushd ${_lispdir}/systems
 
  pushd ${_lispdir}/systems
Line 89: Line 66:
 
  popd
 
  popd
  
...where ''$_lispdir'' is '''${startdir}/pkg/usr/share/common-lisp'''.
+
...where {{ic|$_lispdir}} is {{Ic|$pkgdir/usr/share/common-lisp}}. By linking to a relative, rather than an absolute, path, it's possible to guarantee that the link will not break post-install.
By linking to a relative, rather than an absolute, path, it's possible
+
to guarantee that the link will not break post-install.
+
  
 
== Lisp-specific packaging ==
 
== Lisp-specific packaging ==
 +
When possible, do not make packages specific to a single lisp implementation; try to be as cross-platform as the package itself will allow. If, however, the package is specifically designed for a single lisp implementation (i.e., the developers haven't gotten around to adding support for others yet, or the package's purpose is specifically to provide a capability that is built in to another lisp implementation), it is appropriate to make your Arch package lisp-specific.
  
When possible, do not make packages specific to a single lisp
+
To avoid making packages implementation-specific, ideally all implementation packages (SBCL, cmucl, clisp) would be built with the [[PKGBUILD]] field '''common-lisp'''. However, that's not the case (and that would likely cause problems for people who prefer to have multiple lisps at their fingertips). In the meantime, you could (a) not make your package depend on *any* lisp and include a statement in the package.install file telling folks to make sure they have a lisp
implementation; try to be as cross-platform as the package itself will
+
installed (not ideal), or (b) Take direction from the ''sbcl'' PKGBUILD and include a conditional statement to figure out which lisp
allow. If, however, the package is specifically designed for a single
+
is needed (which is hackish and, again, far from ideal). Other ideas are welcome.
lisp implementation (i.e., the developers haven't gotten around to
+
adding support for others yet, or the package's purpose is
+
specifically to provide a capability that is built in to another lisp
+
implementation), it is appropriate to make your Arch package
+
lisp-specific.
+
  
To avoid making packages implementation-specific, ideally all
+
Also note that if ASDF is needed to install/compile/load the package, things could potentially get awkward as far as dependencies go, since SBCL comes with asdf installed, clisp does not but there is an AUR package, and CMUCL may or may not have it (the author of this doc. knows next to nothing about CMUCL; sorry).
implementation packages (SBCL, cmucl, clisp) would be built with the
+
PKGBUILD field '''common-lisp'''. However, that's not the case (and
+
that would likely cause problems for people who prefer to have
+
multiple lisps at their fingertips). In the meantime, you could (a)
+
not make your package depend on *any* lisp and include a statement in
+
the package.install file telling folks to make sure they have a lisp
+
installed (not ideal), or (b) Take direction from the ''sbcl''
+
PKGBUILD and include a conditional statement to figure out which lisp
+
is needed (which is hackish and, again, far from ideal). Other ideas
+
are welcome.
+
  
Also note that if ASDF is needed to install/compile/load the package,
+
People currently maintaining lisp-specific packages that do not need to be lisp-specific should consider doing at least one of the following:
things could potentially get awkward as far as dependencies go, since
+
SBCL comes with asdf installed, clisp does not but there is an AUR
+
package, and CMUCL may or may not have it (the author of this doc.
+
knows next to nothing about CMUCL; sorry).
+
  
People currently maintaining lisp-specific packages that don't need to
+
* Editing their PKGBUILDs to be cross-platform, provided someone else is not already maintaining the same package for a different lisp.
be lisp-specific should consider doing at least one of the following:
+
 
+
* Editing their PKGBUILD(s) to be cross-platform, provided someone else is not already maintaining the same package for a different lisp.
+
  
 
* Offering to take over maintenance or help with maintenance of the same package for a different lisp, and then combining them into a single package.
 
* Offering to take over maintenance or help with maintenance of the same package for a different lisp, and then combining them into a single package.
Line 131: Line 85:
 
* Offering up their package to the maintainer of a different lisp's version of the same package, so as to allow that person to combine them into a single package.
 
* Offering up their package to the maintainer of a different lisp's version of the same package, so as to allow that person to combine them into a single package.
  
(Note that joyfulgirl, the author of this doc., currently maintains
+
(Note that joyfulgirl, the author of this doc., currently maintains clisp versions of cl-ppcre and of stumpwm; she is open to either
clisp versions of cl-ppcre and of stumpwm; she is open to either
+
giving up the packages to the maintainers of the SBCL versions or to maintain the new, cross-platform versions herself if the SBCL-version maintainers do not want to).
giving up the packages to the maintainers of the SBCL versions or to
+
maintain the new, cross-platform versions herself if the SBCL-version
+
maintainers don't want to).
+
  
 
== Things you, the reader, can do ==
 
== Things you, the reader, can do ==
 
 
* Maintain lisp packages following these guidelines
 
* Maintain lisp packages following these guidelines
 
* Update and fix problems with these guidelines
 
* Update and fix problems with these guidelines

Revision as of 03:45, 28 February 2013

Template:Package Guidelines

At the moment, there are relatively few Lisp packages available in the Arch repositories. This means that at some point or another, more will likely appear. It is useful, therefore, to figure out now, while there are few packages, how they should be packaged.

Directory Structure and Naming

There is at least one package in the base repository (libgpg-error) that includes lisp files, which are placed in /usr/share/common-lisp/source/gpg-error. In keeping with this, other lisp packages should also place their files in /usr/share/common-lisp/source/pkgname.

The package directory should be the name of the lisp package, not what it's called in the Arch repository (or AUR). This applies even to single-file packages.

For example, a Lisp package called "cl-ppcre" should be called cl-ppcre in AUR and reside in /usr/share/common-lisp/source/cl-ppcre. A Lisp package called "alexandria" should be called cl-alexandria in AUR and reside in /usr/share/common-lisp/source/alexandria.

ASDF

Try to avoid the usage of ASDF-Install as a means of installing these system-wide packages.

ASDF itself may be necessary or helpful as a means of compiling and/or loading packages. In that case, it is suggested that the directory used for the central registry (the location of all of the symlinks to *.asd) be /usr/share/common-lisp/systems/.

However, I have observed problems with doing the compilation with asdf as a part of the package compilation process. However, it does work during an install, through use of a package.install file. Such a file might look like this:

cl-ppcre.install
# arg 1:  the new package version
post_install() {
    echo "---> Compiling lisp files <---"

    clisp --silent -norc -x \
        "(load #p\"/usr/share/common-lisp/source/asdf/asdf\") \
        (pushnew #p\"/usr/share/common-lisp/systems/\" asdf:*central-registry* :test #'equal) \
        (asdf:operate 'asdf:compile-op 'cl-ppcre)"

    echo "---> Done compiling lisp files <---"

    cat << EOM

    To load this library, load asdf and then place the following lines
    in your ~/.clisprc.lisp file:

    (push #p"/usr/share/common-lisp/systems/" asdf:*central-registry*)
    (asdf:operate 'asdf:load-op 'cl-ppcre)
EOM
}

post_upgrade() {
    post_install $1
}

pre_remove() {
    rm /usr/share/common-lisp/source/cl-ppcre/{*.fas,*.lib}
}

op=$1
shift

$op $*

Of course, for this example to work, there needs to be a symlink to package.asd in the asdf system directory. During package compilation, a stanza such as this will do the trick...

pushd ${_lispdir}/systems
ln -s ../source/cl-ppcre/cl-ppcre.asd .
ln -s ../source/cl-ppcre/cl-ppcre-test.asd .
popd

...where $_lispdir is $pkgdir/usr/share/common-lisp. By linking to a relative, rather than an absolute, path, it's possible to guarantee that the link will not break post-install.

Lisp-specific packaging

When possible, do not make packages specific to a single lisp implementation; try to be as cross-platform as the package itself will allow. If, however, the package is specifically designed for a single lisp implementation (i.e., the developers haven't gotten around to adding support for others yet, or the package's purpose is specifically to provide a capability that is built in to another lisp implementation), it is appropriate to make your Arch package lisp-specific.

To avoid making packages implementation-specific, ideally all implementation packages (SBCL, cmucl, clisp) would be built with the PKGBUILD field common-lisp. However, that's not the case (and that would likely cause problems for people who prefer to have multiple lisps at their fingertips). In the meantime, you could (a) not make your package depend on *any* lisp and include a statement in the package.install file telling folks to make sure they have a lisp installed (not ideal), or (b) Take direction from the sbcl PKGBUILD and include a conditional statement to figure out which lisp is needed (which is hackish and, again, far from ideal). Other ideas are welcome.

Also note that if ASDF is needed to install/compile/load the package, things could potentially get awkward as far as dependencies go, since SBCL comes with asdf installed, clisp does not but there is an AUR package, and CMUCL may or may not have it (the author of this doc. knows next to nothing about CMUCL; sorry).

People currently maintaining lisp-specific packages that do not need to be lisp-specific should consider doing at least one of the following:

  • Editing their PKGBUILDs to be cross-platform, provided someone else is not already maintaining the same package for a different lisp.
  • Offering to take over maintenance or help with maintenance of the same package for a different lisp, and then combining them into a single package.
  • Offering up their package to the maintainer of a different lisp's version of the same package, so as to allow that person to combine them into a single package.

(Note that joyfulgirl, the author of this doc., currently maintains clisp versions of cl-ppcre and of stumpwm; she is open to either giving up the packages to the maintainers of the SBCL versions or to maintain the new, cross-platform versions herself if the SBCL-version maintainers do not want to).

Things you, the reader, can do

  • Maintain lisp packages following these guidelines
  • Update and fix problems with these guidelines
  • Keep up with what's changed here
  • Provide (polite) thoughts, feedback, and suggestions both on this document and to people's work.
  • Translate this page and future updates to this page.