[Caml-list] oasis packaging questions

[Caml-list] oasis packaging questions

[Daniel Bünzli]

Hello,  

I'd like to support oasis in the various packages I distribute. Here are a few questions (using oasis v0.3.2~rc2). 

1) All the packages I distribute are made of a single module. For now these were just installed as .cmo .cmx .cmxs. Now it seems oasis forces me to create a .mllib even if I have only one module. Is that correct ? 

2) Will the change in 1) have any impact for downstream packagers and is setup.ml enough for them ? 

3) The META plugin doesn't seem to generate the directives for plugins [1], is that right ? Does setup.ml support cmxs generation at all ? 

4) I'm really not interested in oasis trying to generate my _tags and myocamlbuild.ml files. Is it ok to substitute my own or does setup.ml rely on these ? 

5) One of the disadvantages of things like odb is that you may miss valuable information like a CHANGES file, proper documentation or sample programs. These are also things you actually would like to remove when you do a ocamlfind remove. Is there any general agreed on strategy for packages ? Best I think would be to install that along in the package directory with ocamlfind, it makes it relatively easy/evident to lookup. 

6) Regarding 5) I tried to define documentation as follows : 

Document xmlm
Title: "Xmlm documentation and module reference"
Format: html
Index: Xmlm.html 
Install: true
InstallDir: $htmldir/xmlm
DataFiles: README CHANGES doc/*.html, doc/*.css



but ocaml setup -install doesn't seem to install it. Of course this is also certainly a wrong strategy since it would install it in some directory that wouldn't be removed by ocamlfind remove. So how do we achieve that ? 

7) ocaml setup -install seems to install the modules' .mli, .cmi and .cmx by finding them in _build capitalizing the filenames even though they are not (cf. [2]). That works on my case insensitive filesystem, but it mustn't work on others, the original files are not capitalized !? Is that a bug ? 

Thanks, 

Daniel

[1] http://groups.google.com/group/fa.caml/browse_thread/thread/460ba4d505e29c62
[2]
> ocaml setup.ml -install

I: Installing findlib library 'xmlm'
I: Running command '/usr/local/bin/ocamlfind install xmlm src/META _build/src/Xmlm.cmx _build/src/Xmlm.cmi _build/src/xmlm.a _build/src/xmlm.cmxa _build/src/xmlm.cma src/Xmlm.mli'
Installed /usr/local/lib/ocaml/site-lib/xmlm/Xmlm.mli
Installed /usr/local/lib/ocaml/site-lib/xmlm/xmlm.cma
Installed /usr/local/lib/ocaml/site-lib/xmlm/xmlm.cmxa
Installed /usr/local/lib/ocaml/site-lib/xmlm/xmlm.a
Installed /usr/local/lib/ocaml/site-lib/xmlm/Xmlm.cmi
Installed /usr/local/lib/ocaml/site-lib/xmlm/Xmlm.cmx
Installed /usr/local/lib/ocaml/site-lib/xmlm/META

[Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

On 08-03-2012, Daniel Bünzli <daniel.buenzli@erratique.ch> wrote:
> Hello,
>
> I'd like to support oasis in the various packages I distribute. Here are a few questions (using oasis v0.3.2~rc2). 
>
> 1) All the packages I distribute are made of a single module. For now these were just installed as .cmo .cmx .cmxs. Now it seems oasis forces me to create a .mllib even if I have only one module. Is that correct ? 
>

For now yes, but I plan to support only object through an Object
section, just like the Library:
https://forge.ocamlcore.org/tracker/?group_id=54&atid=294&func=detail&aid=790

> 2) Will the change in 1) have any impact for downstream packagers and is setup.ml enough for them ? 
>

The main change of .cmo -> .cma is that toplevel expression are only
evaluated if you open the module. This can be a problem if your .cmo are
used in a plugin way (i.e. toplevel expression register the content of
your library) and that you don't open it.

setup.ml will be enough for me ;-) But I am biased.

> 3) The META plugin doesn't seem to generate the directives for plugins [1], is that right ? Does setup.ml support cmxs generation at all ? 
>

We don't support plugin, indeed. Mostly because I was not aware of it.
setup.ml doesn't yet support .cmxs. I was looking at a patch provided by
Pierre Chambart yesterday evening to do that. Will probably be in 0.3.
https://forge.ocamlcore.org/tracker/?func=detail&group_id=54&aid=898&atid=293
https://forge.ocamlcore.org/tracker/?func=detail&group_id=54&aid=898&atid=293

> 4) I'm really not interested in oasis trying to generate my _tags and myocamlbuild.ml files. Is it ok to substitute my own or does setup.ml rely on these ? 

You can substitute your own. There should be no problem. Don't hesitate
to open a feature request to explain the reason why and your solution. I
don't promise it will be implemented, but it is worth understanding the
reason. 

>
> 5) One of the disadvantages of things like odb is that you may miss valuable information like a CHANGES file, proper documentation or sample programs. These are also things you actually would like to remove when you do a ocamlfind remove. Is there any general agreed on strategy for packages ? Best I think would be to install that along in the package directory with ocamlfind, it makes it relatively easy/evident to lookup. 

We already discuss this CHANGES file stuff. I still didn't have the time
to work on that, but it is something that I want. In future version
there should be something like that.

Use 'PostCleanCommand: rm XYZ'

DataFiles should do that. Concerning installing this using ocamlfind, I
am a little more skeptical. We use standard cp to install in
/usr/share/doc. I don't know a lot of libraries that install their
documentation in /usr/lib, probably because there are packaging rules
against that.

>
> 6) Regarding 5) I tried to define documentation as follows : 
>
> Document xmlm
> Title: "Xmlm documentation and module reference"
> Format: html
> Index: Xmlm.html 
> Install: true
> InstallDir: $htmldir/xmlm
> DataFiles: README CHANGES doc/*.html, doc/*.css
>
>
>
> but ocaml setup -install doesn't seem to install it. Of course this is also certainly a wrong strategy since it would install it in some directory that wouldn't be removed by ocamlfind remove. So how do we achieve that ? 
>

I think the default Type: for document is None, which means do nothing.
You can use "Type: Custom" and have a "XCustomInstall: cp XYZ
$htmldir/xmlm"

I realize that this no good. I probably should code a plugin Static, to
have "Type: Static" and use the data you fill in Document section to
install. This is not a long job.

Could you open a bug about that, so that it will remind me to do it ?

> 7) ocaml setup -install seems to install the modules' .mli, .cmi and .cmx by finding them in _build capitalizing the filenames even though they are not (cf. [2]). That works on my case insensitive filesystem, but it mustn't work on others, the original files are not capitalized !? Is that a bug ? 
>

That is a bug. I have similar problem with the Pack: when generating
_tags with capitalized module name. I installed ocaml on a mac yesterday
to find the right solution. It will be shipped with oais 0.3.0~rc3. But
this part of the bug is not extremly important, because on case
sensitive FS, it will replace the capitalize module name by the right
name. It is a runtime evaluation so no worries on this point.

Cheers,
Sylvain Le Gall

p.s.: please CC-me or oasis-devel@lists.forge.ocamlcore.org, I am not
that often reading caml-list lately
-- 
My company: http://www.ocamlcore.com
Linkedin:   http://fr.linkedin.com/in/sylvainlegall
Start an OCaml project here: http://forge.ocamlcore.org
OCaml blogs:                 http://planet.ocamlcore.org

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 09:31, Sylvain Le Gall a écrit :
> The main change of .cmo -> .cma is that toplevel expression are only
> evaluated if you open the module.  


open, like the construct, I thought open was just about syntax ? You mean use or invoke a function ?
  
> This can be a problem if your .cmo are
> used in a plugin way (i.e. toplevel expression register the content of
> your library) and that you don't open it.


Nevertheless I think it's best for users to avoid the change. Is that Object section still due for 0.3 ? Otherwise is there a way to hack around ?  
  
> setup.ml will be enough for me ;-) But I am biased.

For distribution, I'm fine with that aswell. For developement setup.ml takes too much time to invoke (adds an overhead of 0.5s on my system).  

> > 4) I'm really not interested in oasis trying to generate my _tags and myocamlbuild.ml files. Is it ok to substitute my own or does setup.ml rely on these ?  
>  
> You can substitute your own. There should be no problem. Don't hesitate
> to open a feature request to explain the reason why and your solution. I
> don't promise it will be implemented, but it is worth understanding the
> reason.


First, all my modules don't need an myocamlbuild.ml, second since ocaml 3.12 it is now very easy to express findlib dependencies in _tags files. Third, I don't want to have to sweep through hundreds of generated lines of code (458 for myocamlbuild.ml) of useless configuration stuff when something goes wrong. Avoid bureaucracy at all costs.  
  
> We already discuss this CHANGES file stuff. I still didn't have the time
>  
> to work on that, but it is something that I want. In future version
> there should be something like that.
>  
> Use 'PostCleanCommand: rm XYZ'
>  
> DataFiles should do that.  

You may not have the tarball anymore when you want to uninstall things. That's certainly not a good approach.  
  
> Concerning installing this using ocamlfind, I
> am a little more skeptical. We use standard cp to install in
> /usr/share/doc. I don't know a lot of libraries that install their
> documentation in /usr/lib, probably because there are packaging rules
> against that.

  
I completely disagree with that. I think we already had this discussion. This monolithic view may be suitable for system level packaging system like debian. But I think its wrong to take this approach here. What I need as a developer, is an ocaml specific packaging system that is able to move much quicker than the system level package system and if possible in which you also may install more than one version of a library.  

The only clean approach that seems to work well when you want that is that every package installs in its own (versioned) prefix and symlink *if needed* in the regular system directories (see gnu stow, gobolinux or homebrew on osx). It also makes it *damn simple* to understand who installs what and to hack and understand the system when it breaks.

For me helping downstream packaging should not be the first goal of a system like oasis. From my developer's point of view downstream packaging is only usefull to help you to install the base (the language and the language specific package system) and then you should install what you need by using the language specific package system. Here again I think homebrew takes the right approach, they don't repackage any gem, python egg or perl module, they piggyback on the strength of these individual system and let the developers manage them letting them resort to homebrew only when they need dependencies that are outside the scope of the language specific system (C libraries etc.).  
  
So my proposal would be to let ocamlfind manage all that and agree on a few directories. I'm not proficient enough in ocamlfind but I guess it won't be able to support multiple versions. But at least if we can be sure that `ocamlfind remove <pkg>`, removes everything a package installed, documentation included it would be nice. For me it would be enough to stick the CHANGES, README right into ocamlfind's package directories.  

$SITELIB/<pkg>/META
$SITELIB/<pkg>/_oasis
$SITELIB/<pkg>/README
$SITELIB/<pkg>/CHANGES
$SITELIB/<pkg>/share/html/*.html  
$SITELIB/<pkg>/share/examples/
etc.

Having standard like this could also help efforts like typerex (or even ocamlfind) to know where to lookup for documentation data. Now oasis is the place to enforce such a standard.

> I realize that this no good. I probably should code a plugin Static, to
> have "Type: Static" and use the data you fill in Document section to
> install. This is not a long job.
>  
> Could you open a bug about that, so that it will remind me to do it ?

Here you have. https://forge.ocamlcore.org/tracker/index.php?func=detail&aid=1111&group_id=54&atid=291

> That is a bug. I have similar problem with the Pack: when generating
> _tags with capitalized module name. I installed ocaml on a mac yesterday
> to find the right solution. It will be shipped with oais 0.3.0~rc3. But
> this part of the bug is not extremly important, because on case
> sensitive FS, it will replace the capitalize module name by the right
> name. It is a runtime evaluation so no worries on this point.

Well I'm not sure I follow your explanation. Wild guessing I suspect you derive the file name from the Modules: key and just try different spellings until a Sys.file_exists returns true. But if you first try with a lowercase you'll always get a true on a case insensitive file system even if the actual file starts with an uppercase, and vice versa so the problem seems insoluble that way, I see no other solution than Sys.readdir the build directory and look for the correct spelling in there. Note it's a real problem if you want the tool to be a good unix citizen, for example diffing d1 and d2 with d1/a.ml and d2/A.ml, will report a.ml and A.ml as being different even if you are on a case insensitive file system. Btw. the standard still seems to have lowercased files module files (witness the whole ocaml system itself), in fact I thought this was mandated by the compilers (don't know were I got that), so in any case using lowercase first may be a better approximation.
  
Best,

Daniel

Re: [Caml-list] oasis packaging questions

[Jérémie Dimino]

Le Thu, 8 Mar 2012 01:26:38 +0100,
Daniel Bünzli <daniel.buenzli@erratique.ch> a écrit :

> 1) All the packages I distribute are made of a single module. For now
> these were just installed as .cmo .cmx .cmxs. Now it seems oasis
> forces me to create a .mllib even if I have only one module. Is that
> correct ? 

Note that in general it is better to install a cma/cmxa, even if your
library has only one module. The reason is that when building an
executable, cmo/cmx files passed on the command line are always linked,
while unused units of cma/cmxa files are not (unless you specify
-linkall).

-- 
Jérémie

Re: [Caml-list] oasis packaging questions

[Gerd Stolpmann]

Am Donnerstag, den 08.03.2012, 17:09 +0100 schrieb Jérémie Dimino:
> Le Thu, 8 Mar 2012 01:26:38 +0100,
> Daniel Bünzli <daniel.buenzli@erratique.ch> a écrit :
> 
> > 1) All the packages I distribute are made of a single module. For now
> > these were just installed as .cmo .cmx .cmxs. Now it seems oasis
> > forces me to create a .mllib even if I have only one module. Is that
> > correct ? 
> 
> Note that in general it is better to install a cma/cmxa, even if your
> library has only one module. The reason is that when building an
> executable, cmo/cmx files passed on the command line are always linked,
> while unused units of cma/cmxa files are not (unless you specify
> -linkall).

Right. Just one refinement: if you also install the cmx _in addition to_
the cmxa, you enable cross-module inlining for this particular module.
This is completely optional. I usually do it only when I think it makes
sense. (Cannot comment on how this is handled in oasis.)

Gerd

> -- 
> Jérémie
> 
> 

-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
*** Searching for new projects! Need consulting for system
*** programming in Ocaml? Gerd Stolpmann can help you.
------------------------------------------------------------

Re: [Caml-list] oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 17:09, Jérémie Dimino a écrit :

> Note that in general it is better to install a cma/cmxa, even if your
> library has only one module. The reason is that when building an
> executable, cmo/cmx files passed on the command line are always linked,
> while unused units of cma/cmxa files are not (unless you specify
> -linkall).

Okay, but is there a reasonable case (beyond sloppy dependency tracking) where you'd like to link against a *single module* library while not wanting to use it ?  

Daniel

Re: [Caml-list] oasis packaging questions

[Jérémie Dimino]

Le Thu, 8 Mar 2012 17:36:46 +0100,
Daniel Bünzli <daniel.buenzli@erratique.ch> a écrit :

> > Note that in general it is better to install a cma/cmxa, even if
> > your library has only one module. The reason is that when building
> > an executable, cmo/cmx files passed on the command line are always
> > linked, while unused units of cma/cmxa files are not (unless you
> > specify -linkall).
> 
> Okay, but is there a reasonable case (beyond sloppy dependency
> tracking) where you'd like to link against a *single module* library
> while not wanting to use it ?  

This may happen if you are using a subset of a multi-modules library
which use a single-module one.

-- 
Jérémie

Re: [Caml-list] oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 17:58, Jérémie Dimino a écrit :

> This may happen if you are using a subset of a multi-modules library
> which use a single-module one.

Not completely unlikely I agree.  

I'll go with the cma then.

Thanks,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

Hi,

2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
> Le jeudi, 8 mars 2012 à 09:31, Sylvain Le Gall a écrit :
>> The main change of .cmo -> .cma is that toplevel expression are only
>> evaluated if you open the module.
>
>
> open, like the construct, I thought open was just about syntax ? You mean use or invoke a function ?
>
>> This can be a problem if your .cmo are
>> used in a plugin way (i.e. toplevel expression register the content of
>> your library) and that you don't open it.
>

I think you need to use the function "X.foo" to cause the evaluation
of toplevel statements. But it is something that need to be checked.

>
> Nevertheless I think it's best for users to avoid the change. Is that Object section still due for 0.3 ? Otherwise is there a way to hack around ?
>

I don't think I'll be able to integrate the Object section in 0.3. I
am really planning to release it soon. I just had a quick look at your
git repository and I don't think there will be a difference for user
if it is a .cma (as long as they use ocamlfind).

>> setup.ml will be enough for me ;-) But I am biased.
>
> For distribution, I'm fine with that aswell. For developement setup.ml takes too much time to invoke (adds an overhead of 0.5s on my system).
>

That the parsing time because the file is big. I know this issue and
will try to improve that in the future. I think a 50% down size is
possible, that will bring this time to 250ms. Although, I don't think
that even for development env a 500ms delay is that big... I doubt to
be able to reduce to ~0s.

>> > 4) I'm really not interested in oasis trying to generate my _tags and myocamlbuild.ml files. Is it ok to substitute my own or does setup.ml rely on these ?
>>
>> You can substitute your own. There should be no problem. Don't hesitate
>> to open a feature request to explain the reason why and your solution. I
>> don't promise it will be implemented, but it is worth understanding the
>> reason.
>
>
> First, all my modules don't need an myocamlbuild.ml, second since ocaml 3.12 it is now very easy to express findlib dependencies in _tags files. Third, I don't want to have to sweep through hundreds of generated lines of code (458 for myocamlbuild.ml) of useless configuration stuff when something goes wrong. Avoid bureaucracy at all costs.
>

Never try autoconf ;-)

>> We already discuss this CHANGES file stuff. I still didn't have the time
>>
>> to work on that, but it is something that I want. In future version
>> there should be something like that.
>>
>> Use 'PostCleanCommand: rm XYZ'
>>
>> DataFiles should do that.
>
> You may not have the tarball anymore when you want to uninstall things. That's certainly not a good approach.
>

I suppose you where talking about "make clean", I read too fast, this
is a different issue (ocamlfind remove), which is more a packaging
question (i.e. to the odb/GODI level).

>> Concerning installing this using ocamlfind, I
>> am a little more skeptical. We use standard cp to install in
>> /usr/share/doc. I don't know a lot of libraries that install their
>> documentation in /usr/lib, probably because there are packaging rules
>> against that.
>
>
> I completely disagree with that. I think we already had this discussion. This monolithic view may be suitable for system level packaging system like debian. But I think its wrong to take this approach here. What I need as a developer, is an ocaml specific packaging system that is able to move much quicker than the system level package system and if possible in which you also may install more than one version of a library.
>
> The only clean approach that seems to work well when you want that is that every package installs in its own (versioned) prefix and symlink *if needed* in the regular system directories (see gnu stow, gobolinux or homebrew on osx). It also makes it *damn simple* to understand who installs what and to hack and understand the system when it breaks.
>
> For me helping downstream packaging should not be the first goal of a system like oasis. From my developer's point of view downstream packaging is only usefull to help you to install the base (the language and the language specific package system) and then you should install what you need by using the language specific package system. Here again I think homebrew takes the right approach, they don't repackage any gem, python egg or perl module, they piggyback on the strength of these individual system and let the developers manage them letting them resort to homebrew only when they need dependencies that are outside the scope of the language specific system (C libraries etc.).
>
> So my proposal would be to let ocamlfind manage all that and agree on a few directories. I'm not proficient enough in ocamlfind but I guess it won't be able to support multiple versions. But at least if we can be sure that `ocamlfind remove <pkg>`, removes everything a package installed, documentation included it would be nice. For me it would be enough to stick the CHANGES, README right into ocamlfind's package directories.
>
> $SITELIB/<pkg>/META
> $SITELIB/<pkg>/_oasis
> $SITELIB/<pkg>/README
> $SITELIB/<pkg>/CHANGES
> $SITELIB/<pkg>/share/html/*.html
> $SITELIB/<pkg>/share/examples/
> etc.
>
> Having standard like this could also help efforts like typerex (or even ocamlfind) to know where to lookup for documentation data. Now oasis is the place to enforce such a standard.
>

OK, so first of all you are talking about the odb/GODI/oasis-db level.
OASIS itself is not meant to handle that directly. There will be a
plugin "oasis-db" that will allow you to do "oasis install xmlm" and
"oasis uninstalll xmlm" and fetch the source from
http://oasis.ocamlcore.org but this is the future and this won't be
the core oasis system. You can have a look at odb that allow you to
already do that after having uploaded your package to
http://oasis.ocamlcore.org.

Concerning the ocamlfind install + documentation. I understand you but
it is technically not feasible right now (AFAIK). Simple fact:
ocamlfind cannot install files in subdirectories.

>> That is a bug. I have similar problem with the Pack: when generating
>> _tags with capitalized module name. I installed ocaml on a mac yesterday
>> to find the right solution. It will be shipped with oais 0.3.0~rc3. But
>> this part of the bug is not extremly important, because on case
>> sensitive FS, it will replace the capitalize module name by the right
>> name. It is a runtime evaluation so no worries on this point.
>
> Well I'm not sure I follow your explanation. Wild guessing I suspect you derive the file name from the Modules: key and just try different spellings until a Sys.file_exists returns true. But if you first try with a lowercase you'll always get a true on a case insensitive file system even if the actual file starts with an uppercase, and vice versa so the problem seems insoluble that way, I see no other solution than Sys.readdir the build directory and look for the correct spelling in there. Note it's a real problem if you want the tool to be a good unix citizen, for example diffing d1 and d2 with d1/a.ml and d2/A.ml, will report a.ml and A.ml as being different even if you are on a case insensitive file system. Btw. the standard still seems to have lowercased files module files (witness the whole ocaml system itself), in fact I thought this was mandated by the compilers (don't know were I got that), so in any case using lowercase first may be a better approximation.
>

You understand well, I agree on the fact that lowercase is probably
better. The solution you describe is also the one I will use. For a
Linux guy, this is however not obvious (case insensitive filesystem is
quite uncommon on Linux).

Cheers
Sylvain

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

> I don't think I'll be able to integrate the Object section in 0.3. I
> am really planning to release it soon.

  
For me you can forget about it. Jérémie convinced me that even for single module libraries cma is better (see discussion on list).  

> I just had a quick look at your
> git repository and I don't think there will be a difference for user
> if it is a .cma (as long as they use ocamlfind).

  
I also think so.  

> Never try autoconf ;-)

Never did ! Always scared me away.  

> OK, so first of all you are talking about the odb/GODI/oasis-db level.
> OASIS itself is not meant to handle that directly. There will be a
> plugin "oasis-db" that will allow you to do "oasis install xmlm" and
> "oasis uninstalll xmlm" and fetch the source from
> http://oasis.ocamlcore.org but this is the future and this won't be
> the core oasis system. You can have a look at odb that allow you to
> already do that after having uploaded your package to
> http://oasis.ocamlcore.org.
>  
> Concerning the ocamlfind install + documentation. I understand you but
> it is technically not feasible right now (AFAIK). Simple fact:
> ocamlfind cannot install files in subdirectories.


Ok interesting fact. This raises a few comments/questions.  

1) You tell me that's none of oasis business. But setup.ml sports a -install option so you actually deal with installing things (even if its via ocamlfind). More than that the examples I saw for Document sections are along the lines of copying things to a specific $htmldir so oasis seems to deal with that... At least that's the place where *something* should happen so that the right info gets to the right place.

2) How does godi et al. handle documentation ? I know for sure that odb doesn't do anything about it.

3) Would ocamlfind consider extending its approach to be able to install files in subdirectories ?

I really think that easy access to README, CHANGES and other bits like ocamldoc generated doc is paramount in a good package system since you don't get to see the tarballs anymore. I try to do my best and spend long hours on the documentation of the things I distribute (doesn't mean it's perfect, I sometimes don't understand what I wrote myself...), I want them to be somehow easily accessible (and easily destroyable).  

Can't we agree on something at that level ?  

Best,

Daniel

P.S. Btw. setup.ml -install should maybe also install the _oasis files.

[Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

On 08-03-2012, Gerd Stolpmann <info@gerd-stolpmann.de> wrote:
> Am Donnerstag, den 08.03.2012, 17:09 +0100 schrieb Jérémie Dimino:
>> Le Thu, 8 Mar 2012 01:26:38 +0100,
>> Daniel Bünzli <daniel.buenzli@erratique.ch> a écrit :
>> 
>> > 1) All the packages I distribute are made of a single module. For now
>> > these were just installed as .cmo .cmx .cmxs. Now it seems oasis
>> > forces me to create a .mllib even if I have only one module. Is that
>> > correct ? 
>> 
>> Note that in general it is better to install a cma/cmxa, even if your
>> library has only one module. The reason is that when building an
>> executable, cmo/cmx files passed on the command line are always linked,
>> while unused units of cma/cmxa files are not (unless you specify
>> -linkall).
>
> Right. Just one refinement: if you also install the cmx _in addition to_
> the cmxa, you enable cross-module inlining for this particular module.
> This is completely optional. I usually do it only when I think it makes
> sense. (Cannot comment on how this is handled in oasis.)
>

oasis installs the .cmx by default (if he can found them). No
distinction about "if it makes sense"...


Cheers,
Sylvain Le Gall
-- 
My company: http://www.ocamlcore.com
Linkedin:   http://fr.linkedin.com/in/sylvainlegall
Start an OCaml project here: http://forge.ocamlcore.org
OCaml blogs:                 http://planet.ocamlcore.org

Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

Hi,

2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>> OK, so first of all you are talking about the odb/GODI/oasis-db level.
>> OASIS itself is not meant to handle that directly. There will be a
>> plugin "oasis-db" that will allow you to do "oasis install xmlm" and
>> "oasis uninstalll xmlm" and fetch the source from
>> http://oasis.ocamlcore.org but this is the future and this won't be
>> the core oasis system. You can have a look at odb that allow you to
>> already do that after having uploaded your package to
>> http://oasis.ocamlcore.org.
>>
>> Concerning the ocamlfind install + documentation. I understand you but
>> it is technically not feasible right now (AFAIK). Simple fact:
>> ocamlfind cannot install files in subdirectories.
>
>
> Ok interesting fact. This raises a few comments/questions.
>
> 1) You tell me that's none of oasis business. But setup.ml sports a -install option so you actually deal with installing things (even if its via ocamlfind). More than that the examples I saw for Document sections are along the lines of copying things to a specific $htmldir so oasis seems to deal with that... At least that's the place where *something* should happen so that the right info gets to the right place.

OK, you got me on this. Technically, it is possible to do it using
oasis. We just have to define a dynamic variable that will contain the
directory ocamlfind choose to install the library. It is not trivial
to do and you can set it without enforcing $htmldir.

You have to use "ocaml setup.ml --docdir '$pkg_XYZ_installdir'".

Let say that if you just use $htmldir, it will help whatever packaging
system that cooperate with oasis to enforce it in the future.

To be honest, if it was the only problem I have to solve, I'll be
happy to spend hours on that.

>
> 2) How does godi et al. handle documentation ? I know for sure that odb doesn't do anything about it.

It does it the right way ;-)

$ ls /opt/godi/doc/
apps-oasis      godi-lablgl               godi-ocaml-fileutils  godi-react
apps-ocamlify   godi-lablgtk2             godi-ocamlgraph       godi-sexplib
GODI            godi-lwt                  godi-ocamlmakefile    godi-sqlite3
godi-cryptgps   godi-menhir               godi-ocamlnet         godi-tools
godi-cryptokit  godi-ocaml                godi-ocaml-text       godi-type-conv
godi-extlib     godi-ocaml-data-notation  godi-ounit            godi-zip
godi-findlib    godi-ocaml-expect         godi-pcre             ocsigen

$ ls /opt/godi/doc/apps-oasis/
AUTHORS.txt  CHANGES.txt  COPYING.txt  MANUAL.mkd  oasis  README.txt

(oasis contains the html documentation of the API).

> 3) Would ocamlfind consider extending its approach to be able to install files in subdirectories ?
>
> I really think that easy access to README, CHANGES and other bits like ocamldoc generated doc is paramount in a good package system since you don't get to see the tarballs anymore. I try to do my best and spend long hours on the documentation of the things I distribute (doesn't mean it's perfect, I sometimes don't understand what I wrote myself...), I want them to be somehow easily accessible (and easily destroyable).
>
> Can't we agree on something at that level ?

I would probably object to have html documentation in the $SITELIB of
findlib. However, if there is something to distribute and that should
go in $SITELIB/pkg, it should be a .odoc (compiled ocamldoc generated
using -dump). Among all the possible format, I think this is the
easiest one to use if you want to cooperate with TypeRex (or
Cameleon). Moreover, starting with this .odoc you can generate html
documentation or whatever ocamldoc generator you have at hand.

I think a CHANGES/README is light enough to be in $SITELIB as well.

But all this need to be more widely discuss (with OCamlPro for
TypeRex, Maxence for .odoc/Cameleon, Gerd for ocamlfind and the rest
of  the community to have a real agreement on this point).


> P.S. Btw. setup.ml -install should maybe also install the _oasis files.

Well _oasis can also go there, even though it will be a little bit a
duplicate with META...

Cheers
Sylvain

Re: [Caml-list] Re: oasis packaging questions

[Adrien]

Hi,

On 08/03/2012, Sylvain Le Gall <sylvain@le-gall.net> wrote:
> Hi,
>
> 2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>> Le jeudi, 8 mars 2012 ŕ 09:31, Sylvain Le Gall a écrit :
>>> setup.ml will be enough for me ;-) But I am biased.
>>
>> For distribution, I'm fine with that aswell. For developement setup.ml
>> takes too much time to invoke (adds an overhead of 0.5s on my system).
>>
>
> That the parsing time because the file is big. I know this issue and
> will try to improve that in the future. I think a 50% down size is
> possible, that will bring this time to 250ms. Although, I don't think
> that even for development env a 500ms delay is that big... I doubt to
> be able to reduce to ~0s.

For my own stuff, I've been using a Makefile which includes a rule to
(re)compile setup.ml into an executable with ocamlc.opt (compiling
with ocamlopt was too slow). My usual development machine isn't
terribly fast and this has helped a lot.

I think there was a mention of an issue though but it can help a lot.

Regards,
Adrien Nader

Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

Hi,

2012/3/8 Adrien <camaradetux@gmail.com>:
> Hi,
>
> On 08/03/2012, Sylvain Le Gall <sylvain@le-gall.net> wrote:
>> Hi,
>>
>> 2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>>> Le jeudi, 8 mars 2012 ŕ 09:31, Sylvain Le Gall a écrit :
>>>> setup.ml will be enough for me ;-) But I am biased.
>>>
>>> For distribution, I'm fine with that aswell. For developement setup.ml
>>> takes too much time to invoke (adds an overhead of 0.5s on my system).
>>>
>>
>> That the parsing time because the file is big. I know this issue and
>> will try to improve that in the future. I think a 50% down size is
>> possible, that will bring this time to 250ms. Although, I don't think
>> that even for development env a 500ms delay is that big... I doubt to
>> be able to reduce to ~0s.
>
> For my own stuff, I've been using a Makefile which includes a rule to
> (re)compile setup.ml into an executable with ocamlc.opt (compiling
> with ocamlopt was too slow). My usual development machine isn't
> terribly fast and this has helped a lot.
>
> I think there was a mention of an issue though but it can help a lot.

Make sense. So super quick hack!

Add at the beginning of setup.ml:

let () =
  let setup_ml = Sys.argv.(0) in
  (* Check we are running the script with ocaml, not the compiled mode *)
  if Filename.check_suffix setup_ml ".ml" then
    begin
      let setup_base = Filename.chop_extension setup_ml in
      let setup_digest = setup_base ^ ".digest" in
      let setup_exe =
        Filename.concat
          Filename.current_dir_name
          (setup_base ^ (if Sys.os_type = "Win32" then ".exe" else ""))
      in
      let self_digest =
        let chn = open_in setup_ml in
        let digest = Digest.channel chn (in_channel_length chn) in
          close_in chn;
          digest
      in
      let pre_digest =
        try
          let chn = open_in setup_digest in
          let digest = Digest.input chn in
            close_in chn;
            digest
        with _ ->
          Digest.string ""
      in
      let clean ?(all=false) () =
        List.iter
          (fun fn -> try Sys.remove fn with _ -> ())
          (
            (if all then
               [setup_exe; setup_digest]
             else
               [])
            @
            [setup_base ^ ".cmi"; setup_base ^ ".cmo"]
          )
      in
      if not (Sys.file_exists setup_exe) || self_digest <> pre_digest then
        begin
          match Sys.command "ocamlfind ocamlc -o setup setup.ml" with
            | 0 ->
                (* Compilation succeed, update the digest *)
                let chn = open_out setup_digest in
                  Digest.output chn self_digest;
                  close_out chn;
                  clean ()
            | _ ->
                prerr_endline "E: Compilation of setup.ml doesn't succeed.";
                clean ~all:true ()
        end;
      if Sys.file_exists setup_exe then
        begin
          print_endline "I: Running the compiled version of setup.ml";
          exit
            (Sys.command
               (String.concat " "
                  (List.map Filename.quote
                     (setup_exe :: (List.tl (Array.to_list Sys.argv))))))
        end
    end

Running time:
without the hack -> 500ms
with hack 1st run -> 268ms
with hack 2nd run -> 110ms

Do you think it make sense to include this at the beginning of setup.ml ?

Cheers
Sylvain

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 22:27, Sylvain Le Gall a écrit :

> It does it the right way ;-)
  

The "I'm going to vomit files across your whole file system so that you need another bureaucratic tool/database too keep track of what I did whenever you want to remove me" way. Sure if you're looking for a business model and more bureaucracy that's the way to do it the "right way". The key insight in things like gnu stow or homebrew is that this tool/database already exists, it's the file system itself, KISS principle. And this simplicity also allows you to deal very easily with multiple version installs of the same package.

> I would probably object to have html documentation in the $SITELIB of
> findlib.  


To me that seems to be an ideological objection (debian related I guess), I don't see any technical objection. KISS should be applied here: I installed that package in that directory anything related to it is in that single directory.

> I think a CHANGES/README is light enough to be in $SITELIB as well.

CHANGES and README light, html heavy ? For one thing keep it at least consistent either you choose to put nothing in SITELIB or everything. I don't want to have to lookup two different places for documentation.

> To be honest, if it was the only problem I have to solve, I'll be happy to spend hours on that.

I don't think it's a good idea for the whole system to underestimate the importance of documentation.  

> But all this need to be more widely discuss (with OCamlPro for
> TypeRex, Maxence for .odoc/Cameleon, Gerd for ocamlfind and the rest
> of the community to have a real agreement on this point).


I'm all for it, but now that I'm in these things I want to move forward. So what should I write something like this (currently) nop ?  

Document xmlm
Title: "Xmlm documentation and module reference"
Format: html
Index: Xmlm.html  
Install: true
InstallDir: $docdir
DataFiles: CHANGES README doc/*.html, doc/*.css

Or should I make another Document for CHANGES README ?  

> Well _oasis can also go there, even though it will be a little bit a
> duplicate with META...


It also has much more information in a machine readable format. Like the home page of the project, the maintainers, maybe even the repos etc.  

Best,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 23:26, Sylvain Le Gall a écrit :

> Do you think it make sense to include this at the beginning of setup.ml ?
I just don't see myself using setup.ml during developement, I use a light ("funny" to quote Gabriel Scherer) shell script that has a few targets and falls back to ocamlbuild if nothing matches.  

That way if I quickly want to compile something (e.g. type checking a module) I can just ./build module.cmo. Want to test something, just create test.ml and invoke ./build test.native. If I had to use setup.ml I would first have to write a lot of things into that _oasis file only to remove them later.

But setup.ml seems perfectly fine to me as a standard build script for distribution, keep the focus on that.  
  
Best,

Daniel

Re: [Caml-list] oasis packaging questions

[Stéphane Glondu]

Le 08/03/2012 17:09, Jérémie Dimino a écrit :
> Note that in general it is better to install a cma/cmxa, even if your
> library has only one module. The reason is that when building an
> executable, cmo/cmx files passed on the command line are always linked,
> while unused units of cma/cmxa files are not (unless you specify
> -linkall).

Moreover, in case of bindings, cma/cmxa can contain flags for the linker
so that the end user doesn't have to specify them.


Cheers,

-- 
Stéphane

Re: [Caml-list] Re: oasis packaging questions

[Gerd Stolpmann]

> Le jeudi, 8 mars 2012 à 22:27, Sylvain Le Gall a écrit :
>
>> It does it the right way ;-)
>
>
> The "I'm going to vomit files across your whole file system so that you
> need another bureaucratic tool/database too keep track of what I did
> whenever you want to remove me" way. Sure if you're looking for a business
> model and more bureaucracy that's the way to do it the "right way". The
> key insight in things like gnu stow or homebrew is that this tool/database
> already exists, it's the file system itself, KISS principle. And this
> simplicity also allows you to deal very easily with multiple version
> installs of the same package.

You can call it KISS, but I would call it short-sighted. This has nothing
to do with bureaucracy. Imagine a package has also some utilities to
install (and feeled every second package has). You just don't want to have
to include tons of bin/ directories into your PATH. It does not scale
well, but just slows down your system.

There are just different sets of principles, and they have their pros and
cons. The simplicity argument is not always the striking one.

>> I would probably object to have html documentation in the $SITELIB of
>> findlib.
>
>
> To me that seems to be an ideological objection (debian related I guess),
> I don't see any technical objection. KISS should be applied here: I
> installed that package in that directory anything related to it is in that
> single directory.

That's really funny how you interpret this, but I guess this is just a
matter of perspective. findlib does not support subdirectories just
because I wanted to keep it lean, and to avoid adding features it does not
need for its core job. And the core job is to drive the compiler with the
right flags, and not to provide a container for storing files.


>
>> I think a CHANGES/README is light enough to be in $SITELIB as well.
>
> CHANGES and README light, html heavy ? For one thing keep it at least
> consistent either you choose to put nothing in SITELIB or everything. I
> don't want to have to lookup two different places for documentation.
>
>> To be honest, if it was the only problem I have to solve, I'll be happy
>> to spend hours on that.
>
> I don't think it's a good idea for the whole system to underestimate the
> importance of documentation.

I totally understand your point that you want to have a system that makes
it easy to hack around (it's clearly no fun with the complex guys).
However, I'm really wondering why docs are your first concern here? The
real hacker does not need docs :-)

Gerd


>
>> But all this need to be more widely discuss (with OCamlPro for
>> TypeRex, Maxence for .odoc/Cameleon, Gerd for ocamlfind and the rest
>> of the community to have a real agreement on this point).
>
>
> I'm all for it, but now that I'm in these things I want to move forward.
> So what should I write something like this (currently) nop ?
>
> Document xmlm
> Title: "Xmlm documentation and module reference"
> Format: html
> Index: Xmlm.html
> Install: true
> InstallDir: $docdir
> DataFiles: CHANGES README doc/*.html, doc/*.css
>
> Or should I make another Document for CHANGES README ?
>
>> Well _oasis can also go there, even though it will be a little bit a
>> duplicate with META...
>
>
> It also has much more information in a machine readable format. Like the
> home page of the project, the maintainers, maybe even the repos etc.
>
> Best,
>
> Daniel
>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa-roc.inria.fr/wws/info/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>
>
>


-- 
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
*** Searching for new projects! Need consulting for system
*** programming in Ocaml? Gerd Stolpmann can help you.

Re: [Caml-list] Re: oasis packaging questions

[Anil Madhavapeddy]

On 8 Mar 2012, at 22:26, Sylvain Le Gall wrote:
> 
> 2012/3/8 Adrien <camaradetux@gmail.com>:
>> Hi,
>> 
>> On 08/03/2012, Sylvain Le Gall <sylvain@le-gall.net> wrote:
>>> Hi,
>>> 
>>> 2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>>>> Le jeudi, 8 mars 2012 ŕ 09:31, Sylvain Le Gall a écrit :
>>>>> setup.ml will be enough for me ;-) But I am biased.
>>>> 
>>>> For distribution, I'm fine with that aswell. For developement setup.ml
>>>> takes too much time to invoke (adds an overhead of 0.5s on my system).
>>>> 
>>> 
>>> That the parsing time because the file is big. I know this issue and
>>> will try to improve that in the future. I think a 50% down size is
>>> possible, that will bring this time to 250ms. Although, I don't think
>>> that even for development env a 500ms delay is that big... I doubt to
>>> be able to reduce to ~0s.
>> 
>> For my own stuff, I've been using a Makefile which includes a rule to
>> (re)compile setup.ml into an executable with ocamlc.opt (compiling
>> with ocamlopt was too slow). My usual development machine isn't
>> terribly fast and this has helped a lot.
>> 
>> I think there was a mention of an issue though but it can help a lot.
> 
> Make sense. So super quick hack!
> 
> Add at the beginning of setup.ml:

A Makefile works just fine (and making the autogenerated code less complex
rather than more would be better).

This is the template Makefile I use:
https://github.com/avsm/ocaml-github/blob/master/Makefile

-anil

Re: [Caml-list] Re: oasis packaging questions

[Wojciech Meyer]

> A Makefile works just fine (and making the autogenerated code less complex
> rather than more would be better).
>
> This is the template Makefile I use:
> https://github.com/avsm/ocaml-github/blob/master/Makefile
>

Plus you can generate this file from _oasis, via. DevFiles plugin e.g.

Plugins:      META (0.2), StdFiles (0.2), DevFiles (0.2)

Wojciech

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le vendredi, 9 mars 2012 à 12:56, Gerd Stolpmann a écrit :
> You can call it KISS, but I would call it short-sighted. This has nothing
> to do with bureaucracy. Imagine a package has also some utilities to
> install (and feeled every second package has). You just don't want to have
> to include tons of bin/ directories into your PATH. It does not scale
> well, but just slows down your system.


If you actually took time to have a look the systems I mentioned, they symlink executables in the regular/expected directories in /usr/local. No short-sighting here, sorry, but of course you may have to question some of your pre-conceptions about package management.  
  
> There are just different sets of principles, and they have their pros and
> cons. The simplicity argument is not always the striking one.


Well in my opinion these system solve problems that are known to be complex (like having multiple versions of the same library) in a conceptually very simple and understandable way.  
  
> That's really funny how you interpret this, but I guess this is just a
> matter of perspective. findlib does not support subdirectories just
> because I wanted to keep it lean, and to avoid adding features it does not
> need for its core job. And the core job is to drive the compiler with the
> right flags, and not to provide a container for storing files.


Ah, I thought findlib was a "library manager for Objective Caml". A library without documentation is useless. Frankly, beyond your initial objection, what are the costs and implications of allowing `ocamlfind install` to install files in package subdirectories ?  
  
> I totally understand your point that you want to have a system that makes
> it easy to hack around (it's clearly no fun with the complex guys).


Fundamentally that's not the point, what I want a system that is simple to understand and fix when it breaks. Having easy things like `ocamlfind remove package` removes everything that package installed is part of such a system for me, aswell as simple concepts like everything that this package installed is located in that directory.  
  
> However, I'm really wondering why docs are your first concern here?  


Good documentation and easy access to it makes me productive. I'm sure a lot of other people like to be productive.  

> The
> real hacker does not need docs :-)


I never pretended to be a real hacker... I don't need to show-off, I'm rather limited and actually enjoy simple solutions to complex problems.  

Best,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le jeudi, 8 mars 2012 à 22:27, Sylvain Le Gall a écrit :

> Let say that if you just use $htmldir, it will help whatever packaging  
> system that cooperate with oasis to enforce it in the future.

In fact it is possible to not say anything at all, just don't mention InstallDir, oasis doesn't complain. That allows to abstract away the document's final destination and let the underlying body of code that installs choose what's best. So that's what I have :

Document "reference"
 Title: "Xmlm's documentation and module reference"
 Format: html
 Index: Xmlm.html
 Install: true
 DataFiles: doc/*.html, doc/*.css

Document "distribution"
 Title: "Xmlm's distribution information files"
 Install: true
 DataFiles: README CHANGES

Maybe a kind of enumerated Kind: field could give more information about the nature of the documents. That said, oasis still seems to be a little bit schizophrenic about installation: on one hand it shouldn't install, on the other hand it seems to offer fields to perform installation duties.  

Best,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

Hi,

2012/3/9 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>
>
> Le jeudi, 8 mars 2012 à 22:27, Sylvain Le Gall a écrit :
>
>> Let say that if you just use $htmldir, it will help whatever packaging
>> system that cooperate with oasis to enforce it in the future.
>
> In fact it is possible to not say anything at all, just don't mention InstallDir, oasis doesn't complain. That allows to abstract away the document's final destination and let the underlying body of code that installs choose what's best. So that's what I have :
>
> Document "reference"
>  Title: "Xmlm's documentation and module reference"
>  Format: html
>  Index: Xmlm.html
>  Install: true
>  DataFiles: doc/*.html, doc/*.css
>
> Document "distribution"
>  Title: "Xmlm's distribution information files"
>  Install: true
>  DataFiles: README CHANGES
>
> Maybe a kind of enumerated Kind: field could give more information about the nature of the documents. That said, oasis still seems to be a little bit schizophrenic about installation: on one hand it shouldn't install, on the other hand it seems to offer fields to perform installation duties.
>

I am probably off-topic, because I don't understand by what you mean
by "on one hand it shouldn't install, on the other hand it seems to
offer fields to perform installation duties." ?

It should install, if that is not installing, that is a bug (the
Static plugin I told would solve that). But maybe what you miss here,
is that it is meant to build documentation. E.g setting "Type:
ocamlbuild" + a couple of field to tell that your doc will be
extracted from some libraries/module and build using ocamldoc +
ocamlbuild:

 Document "api-ounit"
    Title:       API reference for OUnit
    Type:        ocamlbuild (0.2)
    BuildTools+: ocamldoc
    XOCamlbuildLibraries: oUnit
    XOCamlbuildPath:      src/

Cheers
Sylvain

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

Le vendredi, 9 mars 2012 à 20:11, Sylvain Le Gall a écrit :

> >  
> > Document "reference"
> > Title: "Xmlm's documentation and module reference"
> > Format: html
> > Index: Xmlm.html
> > Install: true
> > DataFiles: doc/*.html, doc/*.css
> >  
> > Document "distribution"
> > Title: "Xmlm's distribution information files"
> > Install: true
> > DataFiles: README CHANGES
> >  
> > Maybe a kind of enumerated Kind: field could give more information about the nature of the documents. That said, oasis still seems to be a little bit schizophrenic about installation: on one hand it shouldn't install, on the other hand it seems to offer fields to perform installation duties.
>  
> I am probably off-topic, because I don't understand by what you mean
> by "on one hand it shouldn't install, on the other hand it seems to
> offer fields to perform installation duties." ?


I was meaning in general. If oasis is supposed to be descriptive (in the sense here you have an executable, here you have a library, here you have documentation), why does it have a field like InstallDir for documents ? Why do we have something like XCustomInstall: cp XYZ; I mean understand why we have it, but shouldn't its usage be discouraged ?  

Now the Document sections I wrote above don't do anything for now but it seems to me that  

1) It has the info for a potential downstream packager e.g. cp `oasis query Doc(reference)` $WHEREWEPUTTHATINOURDISTRIB  
2) It has the info for the thing I choose to manage the oasis -install  

I hope that one day, that 2) will be able to its thing and push it at the right place (being it inside sitelib or not !). Isn't that a better approach than using XCustomInstall or InstallDir ? Should I do it differently ?
  
Maybe the only thing that is missing in an agreement like you have for SourceRepository: this, head. to better caracterize the actual bits of documentation that are being described (b.t.w I added a Document samples with DataFiles:examples/*.ml)

> But maybe what you miss here,
> is that it is meant to build documentation.

  
Yes, if eventually there's a system that is able to integerates these odocl why not. For now I don't see any advantage and I prefer to distribute them statically. One reason is that since all my documentation is in inside the .mlis I think its nice if someone just want to have a look at the docs that he doesn't need to build anything (e.g. if the lib has many deps).   

Best,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Daniel Bünzli]

> E.g setting "Type:
> ocamlbuild" + a couple of field to tell that your doc will be
> extracted from some libraries/module and build using ocamldoc +
> ocamlbuild:
> 
> Document "api-ounit"
> Title: API reference for OUnit
> Type: ocamlbuild (0.2)
> BuildTools+: ocamldoc
> XOCamlbuildLibraries: oUnit
> XOCamlbuildPath: src/

In fact I may change my mind about that (since I already publish docs on the web). Two questions : 

1) In the manual under the library section it's written : 

"Define an OCaml library. OCaml API is generated using `ocamldoc` applied to
`Modules` with `BuildDepends` required flags."

is that outdated info ? because in that case I don't even need to define a section like you do above.

2) In both cases how can I pass arguments to ocamldoc (I need to give it a -charset utf-8). 

Best,

Daniel

Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall]

Hi,

2012/3/9 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>> E.g setting "Type:
>> ocamlbuild" + a couple of field to tell that your doc will be
>> extracted from some libraries/module and build using ocamldoc +
>> ocamlbuild:
>>
>> Document "api-ounit"
>> Title: API reference for OUnit
>> Type: ocamlbuild (0.2)
>> BuildTools+: ocamldoc
>> XOCamlbuildLibraries: oUnit
>> XOCamlbuildPath: src/
>
> In fact I may change my mind about that (since I already publish docs on the web). Two questions :
>
> 1) In the manual under the library section it's written :
>
> "Define an OCaml library. OCaml API is generated using `ocamldoc` applied to
> `Modules` with `BuildDepends` required flags."
>
> is that outdated info ? because in that case I don't even need to define a section like you do above.

No you are right, this is 'semi'-outdated info. It is only 'semi'
because this behavior is till handled by the OCamlbuild plugin, once
you have attached libraries to it.

A good example is
http://darcs.ocamlcore.org/cgi-bin/darcsweb.cgi?r=ounit/ounit;a=headblob;f=/_oasis

Basically, you attach library to this document using
'XOCamlbuildLibraries: oUnit' (you can attach more than if you want,
but I think it is no use for you).

>
> 2) In both cases how can I pass arguments to ocamldoc (I need to give it a -charset utf-8).
>

Good catch and the answer is "you can't". I think this is worth a
feature request.

Cheers
Sylvain

Re: [Caml-list] Re: oasis packaging questions

[Francois Berenger]

On 03/09/2012 09:22 PM, Anil Madhavapeddy wrote:
> On 8 Mar 2012, at 22:26, Sylvain Le Gall wrote:
>>
>> 2012/3/8 Adrien<camaradetux@gmail.com>:
>>> Hi,
>>>
>>> On 08/03/2012, Sylvain Le Gall<sylvain@le-gall.net>  wrote:
>>>> Hi,
>>>>
>>>> 2012/3/8 Daniel Bünzli<daniel.buenzli@erratique.ch>:
>>>>> Le jeudi, 8 mars 2012 ŕ 09:31, Sylvain Le Gall a écrit :
>>>>>> setup.ml will be enough for me ;-) But I am biased.
>>>>>
>>>>> For distribution, I'm fine with that aswell. For developement setup.ml
>>>>> takes too much time to invoke (adds an overhead of 0.5s on my system).
>>>>>
>>>>
>>>> That the parsing time because the file is big. I know this issue and
>>>> will try to improve that in the future. I think a 50% down size is
>>>> possible, that will bring this time to 250ms. Although, I don't think
>>>> that even for development env a 500ms delay is that big... I doubt to
>>>> be able to reduce to ~0s.
>>>
>>> For my own stuff, I've been using a Makefile which includes a rule to
>>> (re)compile setup.ml into an executable with ocamlc.opt (compiling
>>> with ocamlopt was too slow). My usual development machine isn't
>>> terribly fast and this has helped a lot.
>>>
>>> I think there was a mention of an issue though but it can help a lot.
>>
>> Make sense. So super quick hack!
>>
>> Add at the beginning of setup.ml:
>
> A Makefile works just fine (and making the autogenerated code less complex
> rather than more would be better).

May I suggest to generate an OcamlMakefile instead of a plain Makefile? :)
It might be simpler to generate, I think.

> This is the template Makefile I use:
> https://github.com/avsm/ocaml-github/blob/master/Makefile
>
> -anil
>

Re: [Caml-list] Re: oasis packaging questions

[Damien Doligez]

On 2012-03-08, at 16:36, Daniel Bünzli wrote:

> Btw. the standard still seems to have lowercased files module files (witness the whole ocaml system itself), in fact I thought this was mandated by the compilers (don't know were I got that),


It was mandatory before version 3.07 (released in 2003).

-- Damien