[Caml-list] OPAM conventions

[Caml-list] OPAM conventions

[Dario Teixeira]

Hi,

I've been looking at the OPAM package database -- trying to determine overall
conventions and best practices -- and I came across some inconsistencies.
Though in most cases these are purely cosmetical, I reckon that nevertheless
we could all benefit if some standardisation is agreed upon on.  Examples:

1) Package naming

   For some values of "foo", OPAM's package name for project "ocaml-foo"
   is also "ocaml-foo", whereas for others is simply "foo".  This is an
   ackowledged issue by OPAM developers:
   https://github.com/OCamlPro/opam-repository/issues/163

  In my mind, there are only two sensible policies for naming OPAM packages:

  a) OPAM packages should preserve the name of the original project.
     Thus, if the project is named "ocaml-foo", the OPAM package will
     also be "ocaml-foo".

  b) OPAM packages should have the same name as the findlib entry.
     If project "ocaml-foo" registers itself in findlib with name
     "foo", then "foo" should also be the name of the OPAM package.

   Good arguments can be made for and against each option.  Though this
   is largely a bike-shedding issue, I think the community should make
   a decision sooner rather than later.

2) Invoking executables

   To invoke, say, a configure script, some packages will nonchalantly
   just declare ["./configure"] whereas others will ask the shell to
   do it: ["sh" "configure"].  While either should work in any Unix
   system, should one be preferred for compatibility with more exotic
   systems?

3) Package removal

   For most values of "foo", package "foo" will just declare ["ocamlfind"
   "remove" "foo"].  However, this approach seems a bit brittle to me.
   If the Makefile supports "uninstall" (which is the usually the case
   for OASIS packages), then I reckon that ["%{make}%" "uninstall"]
   should be preferred.

   Having said that, it seems that ["%{make}%" "uninstall"] is currently
   not working (OPAM tries to download the package de novo upon removal!).
   Is this a bug or a feature?

4) Findlib dependency

   Most packages do declare a dependency on ocamlfind.  However, this is
   not universal, even for packages that do register themselves with findlib.
   What should be the standard here: always declare a dependency, or omit
   it altogether since it is implied?

Thank you for your attention!
Best regards,
Dario Teixeira

Re: [Caml-list] OPAM conventions

[Markus Mottl]

On Wed, Dec 12, 2012 at 9:47 AM, Dario Teixeira <darioteixeira@yahoo.com> wrote:
>   In my mind, there are only two sensible policies for naming OPAM packages:
>
>   a) OPAM packages should preserve the name of the original project.
>      Thus, if the project is named "ocaml-foo", the OPAM package will
>      also be "ocaml-foo".
>
>   b) OPAM packages should have the same name as the findlib entry.
>      If project "ocaml-foo" registers itself in findlib with name
>      "foo", then "foo" should also be the name of the OPAM package.
>
>    Good arguments can be made for and against each option.  Though this
>    is largely a bike-shedding issue, I think the community should make
>    a decision sooner rather than later.

I usually use the following naming conventions when releasing open
source libraries: if it is derived from some other (usually C-)
library, e.g. "pcre", then I add the suffix "-ocaml" to the
distribution file name to avoid confusing binary packagers.  I would
then release e.g. "pcre-ocaml-3.42.tar.gz".  If the library is not
derived from anything else, then the findlib name will be used to name
the distribution.  Findlib names should never have an "ocaml" suffix
or prefix, because it's clear that a findlib package is for OCaml
only.  Since OPAM is an OCaml tool, I'd suggest dropping the "ocaml"
suffixes or prefixes from its package names, too.

> 3) Package removal
>
>    For most values of "foo", package "foo" will just declare ["ocamlfind"
>    "remove" "foo"].  However, this approach seems a bit brittle to me.
>    If the Makefile supports "uninstall" (which is the usually the case
>    for OASIS packages), then I reckon that ["%{make}%" "uninstall"]
>    should be preferred.

That's a good question, which essentially boils down to how package
developers should specify configuring, building, installing, and
uninstalling packages.  I guess it would be healthy in the long term
to settle on a commonly used specification, possibly the Oasis format.
 One could then agree to always just call "configure" and "make" in
standardized ways under the assumption that these will behave as if
these scripts had been generated by Oasis (whether or not this is
actually the case).

> 4) Findlib dependency
>
>    Most packages do declare a dependency on ocamlfind.  However, this is
>    not universal, even for packages that do register themselves with findlib.
>    What should be the standard here: always declare a dependency, or omit
>    it altogether since it is implied?

I think findlib should be standard and implied as a dependency.  I
don't think people would be happy if forced to use libraries that
don't install with findlib.

Regards,
Markus

-- 
Markus Mottl        http://www.ocaml.info        markus.mottl@gmail.com

Re: [Caml-list] OPAM conventions

[Anil Madhavapeddy]

On 12 Dec 2012, at 14:47, Dario Teixeira <darioteixeira@yahoo.com> wrote:

> Hi,
> 
> I've been looking at the OPAM package database -- trying to determine overall
> conventions and best practices -- and I came across some inconsistencies.
> Though in most cases these are purely cosmetical, I reckon that nevertheless
> we could all benefit if some standardisation is agreed upon on.  Examples:
> 
> 1) Package naming
> 
>    For some values of "foo", OPAM's package name for project "ocaml-foo"
>    is also "ocaml-foo", whereas for others is simply "foo".  This is an
>    ackowledged issue by OPAM developers:
>    https://github.com/OCamlPro/opam-repository/issues/163
> 
>   In my mind, there are only two sensible policies for naming OPAM packages:
> 
>   a) OPAM packages should preserve the name of the original project.
>      Thus, if the project is named "ocaml-foo", the OPAM package will
>      also be "ocaml-foo".
> 
>   b) OPAM packages should have the same name as the findlib entry.
>      If project "ocaml-foo" registers itself in findlib with name
>      "foo", then "foo" should also be the name of the OPAM package.
> 
>    Good arguments can be made for and against each option.  Though this
>    is largely a bike-shedding issue, I think the community should make
>    a decision sooner rather than later.

I generally don't like typing too much, and so prefer the shorter name.
But converting packages names isn't really a big deal and can be done
mechanically, so it's more important to build up the database first.

> 
> 2) Invoking executables
> 
>    To invoke, say, a configure script, some packages will nonchalantly
>    just declare ["./configure"] whereas others will ask the shell to
>    do it: ["sh" "configure"].  While either should work in any Unix
>    system, should one be preferred for compatibility with more exotic
>    systems?

If the upstream package has the configure script marked as executable,
then ./configure should be fine.  Some don't (this used to be a bigger
problem when some VCS's couldn't track file modes, but isn't an issue
in modern systems).

> 3) Package removal
> 
>    For most values of "foo", package "foo" will just declare ["ocamlfind"
>    "remove" "foo"].  However, this approach seems a bit brittle to me.
>    If the Makefile supports "uninstall" (which is the usually the case
>    for OASIS packages), then I reckon that ["%{make}%" "uninstall"]
>    should be preferred.
> 
>    Having said that, it seems that ["%{make}%" "uninstall"] is currently
>    not working (OPAM tries to download the package de novo upon removal!).
>    Is this a bug or a feature?

The issue with removal is that the package needs to be available to run
make uninstall, hence the download.

In the longer term, we've discussed letting the OPAM package declare
which ocamlfind packages it installs, and having those automatically
handled (i.e. the install phase asserts that the package exists as a
post-condition, and the uninstall removes it and checks it's gone).

But that's all post-OPAM-1.0! Basics first.

> 4) Findlib dependency
> 
>    Most packages do declare a dependency on ocamlfind.  However, this is
>    not universal, even for packages that do register themselves with findlib.
>    What should be the standard here: always declare a dependency, or omit
>    it altogether since it is implied?

If something uses ocamlfind and doesn't declare it explicitly, it's a bug.
The continuous build system catches most of these, and in practise it doesn't
matter as a dependent package will pull it in, but it's best to be explicit
about it.

-anil

Re: [Caml-list] OPAM conventions

[Wojciech Meyer]

On Wed, Dec 12, 2012 at 5:36 PM, Anil Madhavapeddy <anil@recoil.org> wrote:
> On 12 Dec 2012, at 14:47, Dario Teixeira <darioteixeira@yahoo.com> wrote:
>>    Good arguments can be made for and against each option.  Though this
>>    is largely a bike-shedding issue, I think the community should make
>>    a decision sooner rather than later.
>
> I generally don't like typing too much, and so prefer the shorter name.
> But converting packages names isn't really a big deal and can be done
> mechanically, so it's more important to build up the database first.

Indeed, but then dependent packages needs to be up-dated too!
We could have also virtual packages that could serve as a basis for
aliases when there is a strong reason to be compatible.
The good thing is that OPAM package definitions are detached from the
tarballs itself, so it's easy to up-date in a centralised way.

>> 3) Package removal
>>
>>    For most values of "foo", package "foo" will just declare ["ocamlfind"
>>    "remove" "foo"].  However, this approach seems a bit brittle to me.
>>    If the Makefile supports "uninstall" (which is the usually the case
>>    for OASIS packages), then I reckon that ["%{make}%" "uninstall"]
>>    should be preferred.
>>
>>    Having said that, it seems that ["%{make}%" "uninstall"] is currently
>>    not working (OPAM tries to download the package de novo upon removal!).
>>    Is this a bug or a feature?
>
> The issue with removal is that the package needs to be available to run
> make uninstall, hence the download.

Hmm, wouldn't be just better for OPAM to track the diff of the
repository, then just remove the files?
Possibly, having an open door for unnistall would be good for packages
like Ocsigen which might want to remove the configuration from the
system or shutdown the server.

>
> In the longer term, we've discussed letting the OPAM package declare
> which ocamlfind packages it installs, and having those automatically
> handled (i.e. the install phase asserts that the package exists as a
> post-condition, and the uninstall removes it and checks it's gone).
>
> But that's all post-OPAM-1.0! Basics first.
>
>> 4) Findlib dependency
>>
>>    Most packages do declare a dependency on ocamlfind.  However, this is
>>    not universal, even for packages that do register themselves with findlib.
>>    What should be the standard here: always declare a dependency, or omit
>>    it altogether since it is implied?
>
> If something uses ocamlfind and doesn't declare it explicitly, it's a bug.
> The continuous build system catches most of these, and in practise it doesn't
> matter as a dependent package will pull it in, but it's best to be explicit
> about it.

+1.

I'm also always convinced that ocamlfind should be taken into account
as an integral part of the system.

-Wojciech