Difference between revisions of "OCaml package guidelines"

From ArchWiki
Jump to: navigation, search
(OCaml PKGBUILD Example: removed useless || return 1)
(fix typo)
(31 intermediate revisions by 9 users not shown)
Line 1: Line 1:
[[Category:Package development (English)]]
+
[[Category:Package development]]
[[Category:Guidelines (English)]]
+
[[it:OCaml Package Guidelines]]
 +
{{Package Guidelines}}
  
==Package Naming==
+
Writing [[PKGBUILD]]s for software written in [[Wikipedia:OCaml|OCaml]].
For libraries, use ''ocaml-modulename''. For applications, use the program name. In either case, the pkgname should be entirely lowercase.
+
  
==OCaml Library Locations==
+
==Package naming==
All OCaml libraries should be installed via ocaml-findlib, ocaml-findlib maintains a means whereby ocaml packages are more clearly tracked. The only distinction for ocaml-findlib is that it requires that a META file be created. Most OCaml packages already have a META file, for those which do not provide an upstream META file chances are the file can be obtained from the Debian/Ubuntu or Fedora package.
+
For libraries, use {{ic|ocaml-''modulename''}}. For applications, use the program name. In either case, the name should be entirely lowercase.
  
The OCaml libraries should all be installed under /usr/lib/ocaml, there has been some confusion about where to install OCaml libraries, and many OCaml libraries have been installed under /usr/lib/ocaml/site-lib, this practice can break a number of OCaml program builds and has resulted in a schism in OCaml package development. Maintaining a central location for all OCaml packages will aleviate a number of problems with the continued development of ArchLinux OCaml support.
+
==File placement==
 +
=== Libraries ===
 +
OCaml libraries should be installed under {{ic|/usr/lib/ocaml}}. Installation in {{ic|/usr/lib/ocaml/site-lib}} is deprecated.
  
In most packages the OCaml findlib directory will need to be specified, this should never be specified statically, but should use the ocaml-findlib destdir variable. Generally this is set in this manner:
+
OCaml libraries should be installed using {{Pkg|ocaml-findlib}}. {{ic|ocaml-findlib}} includes library metadata in the package that makes it easy to manage libraries. It is a de-facto standard and a lot of OCaml software now requires it.
OCAMLFIND_DESTDIR=${pkgdir}/$(ocamlfind printconf destdir)
+
  
== Bytecode ==
+
{{ic|ocaml-findlib}} extracts necessary data from a file named {{ic|META}} that should be included in the source archive. If this file is not included, one should either be obtained from the corresponding Debian, Ubuntu, or Fedora package, or created for the package by the maintainer. A request to include the file should also be made to the upstream developers of the package.
If bytecode is produced make sure to include "options=('!strip')". Otherwise the packaging process will damage the OCaml bytecode.
+
  
== OCaml PKGBUILD Example ==
+
The {{ic|OCAMLFIND_DESTDIR}} variable should be used when installing packages with {{ic|ocaml-findlib}}. See the example PKGBUILD below for details.
<pre>
+
 
 +
=== OASIS ===
 +
OCaml packages that install executables using OASIS ignore {{ic|DESTDIR}}. This is a known limitation of OASIS ([https://forge.ocamlcore.org/tracker/?func=detail&atid=294&aid=852&group_id=54 issue #852]). One way to enable {{ic|DESTDIR}}-like functionality is to run the {{ic|configure}} script with the {{ic|--destdir}} argument, like so:
 +
 
 +
{{bc|<nowiki>build() {
 +
    cd "${srcdir}/${srcname}-${pkgver}"
 +
    ./configure --prefix /usr --destdir "$pkgdir"
 +
 
 +
    # build commands
 +
}</nowiki>}}
 +
 
 +
== OCaml bytecode and levels ==
 +
 
 +
OCaml can run code on multiple "levels", the top level interprets OCaml Code without compiling, the bytecode level creates machine independent bytecode and the native level creates machine code binaries (just like C/C++).
 +
 
 +
When building OCaml Packages you need to be aware if the build process is compiling native machine code, bytecode, or as in many cases both. This creates a number of situations which can cause problems with package options and the right dependencies.
 +
 
 +
If bytecode is produced at all then the PKGBUILD must contain the following to protect the bytecode:
 +
 
 +
options=('!strip')
 +
 
 +
If the package does not contain bytecode and only distributes a binary, then {{ic|ocaml}} is not needed as a dependency, but it of course is required as a makedepends since the {{ic|ocaml}} package provides the OCaml compiler. If the package contains both native code and bytecode then {{ic|ocaml}} should be a dependency and a makedepends.
 +
 
 +
OCaml code is rarely (if ever) distributed as bytecode only and will almost always include native code: the only case where using ''any'' as the ''arch'' is advisable is when only un-compiled source code is distributed, usually with a library, though many libraries still distribute native code.
 +
 
 +
The moral of the story here is to be aware of what it is you are distributing, chances are your package contains both native machine code and bytecode.
 +
 
 +
== Example PKGBUILD ==
 +
 
 +
{{bc|1=
 
# Contributor: Your Name <youremail@domain.com>
 
# Contributor: Your Name <youremail@domain.com>
  
Line 23: Line 52:
 
pkgver=4.2
 
pkgver=4.2
 
pkgrel=1
 
pkgrel=1
license=('GPL')
+
license=('')
 
arch=('i686' 'x86_64')
 
arch=('i686' 'x86_64')
 
pkgdesc="An OCaml Package"
 
pkgdesc="An OCaml Package"
 
url=""
 
url=""
depends=()
+
depends=('ocaml')
makedepends=('ocaml' 'ocaml-findlib')
+
makedepends=('ocaml-findlib')
 
source=()
 
source=()
 
options=('!strip')
 
options=('!strip')
 
md5sums=()
 
md5sums=()
 +
 +
OCAMLFIND_DESTDIR="${pkgdir}$(ocamlfind printconf destdir)"
  
 
build() {
 
build() {
   cd "${startdir}/src/${pkgname}-${pkgver}"
+
   cd "${srcdir}/${pkgname}-${pkgver}"
  OCAMLFIND_DESTDIR="${pkgdir}$(ocamlfind printconf destdir)"
+
   mkdir -p "$OCAMLFIND_DESTDIR"
   mkdir -p $OCAMLFIND_DESTDIR
+
 
   ./configure --prefix=/usr
 
   ./configure --prefix=/usr
 
   make
 
   make
  env DESTDIR=${pkgdir} \
 
    OCAMLFIND_DESTDIR=$OCAMLFIND_DESTDIR \
 
    make install
 
 
 
}
 
}
  
</pre>
+
package() {
 +
  cd "${srcdir}/${pkgname}-${pkgver}"
 +
  env DESTDIR="${pkgdir}" \
 +
    OCAMLFIND_DESTDIR="$OCAMLFIND_DESTDIR" \
 +
    make install
 +
}
 +
}}
  
Keep in mind that many OCaml Packages will often need extra parameters passed to make and make install.
+
Keep in mind that many OCaml Packages will often need extra parameters passed to make and make install. Also remember to remove the'' '!strip' ''option and change the architecture if the package does not produce bytecode.

Revision as of 23:18, 16 February 2014

Template:Package Guidelines

Writing PKGBUILDs for software written in OCaml.

Package naming

For libraries, use ocaml-modulename. For applications, use the program name. In either case, the name should be entirely lowercase.

File placement

Libraries

OCaml libraries should be installed under /usr/lib/ocaml. Installation in /usr/lib/ocaml/site-lib is deprecated.

OCaml libraries should be installed using ocaml-findlib. ocaml-findlib includes library metadata in the package that makes it easy to manage libraries. It is a de-facto standard and a lot of OCaml software now requires it.

ocaml-findlib extracts necessary data from a file named META that should be included in the source archive. If this file is not included, one should either be obtained from the corresponding Debian, Ubuntu, or Fedora package, or created for the package by the maintainer. A request to include the file should also be made to the upstream developers of the package.

The OCAMLFIND_DESTDIR variable should be used when installing packages with ocaml-findlib. See the example PKGBUILD below for details.

OASIS

OCaml packages that install executables using OASIS ignore DESTDIR. This is a known limitation of OASIS (issue #852). One way to enable DESTDIR-like functionality is to run the configure script with the --destdir argument, like so:

build() {
    cd "${srcdir}/${srcname}-${pkgver}"
    ./configure --prefix /usr --destdir "$pkgdir"

    # build commands
}

OCaml bytecode and levels

OCaml can run code on multiple "levels", the top level interprets OCaml Code without compiling, the bytecode level creates machine independent bytecode and the native level creates machine code binaries (just like C/C++).

When building OCaml Packages you need to be aware if the build process is compiling native machine code, bytecode, or as in many cases both. This creates a number of situations which can cause problems with package options and the right dependencies.

If bytecode is produced at all then the PKGBUILD must contain the following to protect the bytecode:

options=('!strip')

If the package does not contain bytecode and only distributes a binary, then ocaml is not needed as a dependency, but it of course is required as a makedepends since the ocaml package provides the OCaml compiler. If the package contains both native code and bytecode then ocaml should be a dependency and a makedepends.

OCaml code is rarely (if ever) distributed as bytecode only and will almost always include native code: the only case where using any as the arch is advisable is when only un-compiled source code is distributed, usually with a library, though many libraries still distribute native code.

The moral of the story here is to be aware of what it is you are distributing, chances are your package contains both native machine code and bytecode.

Example PKGBUILD

# Contributor: Your Name <youremail@domain.com>

pkgname=ocaml-<package name>
pkgver=4.2
pkgrel=1
license=()
arch=('i686' 'x86_64')
pkgdesc="An OCaml Package"
url=""
depends=('ocaml')
makedepends=('ocaml-findlib')
source=()
options=('!strip')
md5sums=()

OCAMLFIND_DESTDIR="${pkgdir}$(ocamlfind printconf destdir)"

build() {
  cd "${srcdir}/${pkgname}-${pkgver}"
  mkdir -p "$OCAMLFIND_DESTDIR"
  ./configure --prefix=/usr
  make
}

package() {
  cd "${srcdir}/${pkgname}-${pkgver}"
  env DESTDIR="${pkgdir}" \
    OCAMLFIND_DESTDIR="$OCAMLFIND_DESTDIR" \
    make install
}

Keep in mind that many OCaml Packages will often need extra parameters passed to make and make install. Also remember to remove the '!strip' option and change the architecture if the package does not produce bytecode.