Re: [MirageOS-devel] TFTP, Oasis, OPAM, Structuring modules, and Docs

[Thomas Gazagnaire <thomas@xxxxxxxxxxxxxx>]

hey,

> 1. Where's the best place to look for examples of how to setup a
> project to use Oasis and publish through OAPM?  I hacked something
> together from examination of some recent projects, primarily due to
> @samoht and @dsheets, but the documentation generally seemed sparse
> and rather out-of-date. (If it really is that bad, I'm happy to start
> filing issues if someone points me appropriately :)

there is no complete and up-to-date doc on that - below are very rought notes 
of my workflow (which appears to be very different from other people). Since a 
couple of weeks I'm also using [1] to help release and it's quite useful (when 
it works). I was maybe planning to write something similar to publish docs (or 
adapt[2] to run as a script) but it is not done yet.

[1]: https://github.com/samoht/opam-release
[2]: 
https://github.com/simonjbeaumont/ocaml-travisci-skeleton/blob/docgen/.travis-docgen.sh

> 2. Is there a recommended way to structure an OCaml library for use by
> ocamlfind and Mirage that's fairly lightweight (ie., not
> ocaml-cohttp's functorise all the things approach)? In this case I
> wanted to pack S and Wire under Tftp, but still expose two separate
> ocamlfind packages, tftp and tftp.wire. The packing seems to work, but
> I end up with #require "tftp.wire";; exposing just Wire, which doesn't
> seem entirely satisfactory.  I'm happy to tie to recent compiler
> releases (4.02 and above) if it will make things significantly better.

if you pack things, they have to be in the same ocamlfind library. A possible 
workaround is to add prefix to the module names (Tftp_wirte and Tftp) and keep 
the two ocamlfind packages. If you have unix dependencies, one common scheme is 
to have Tftp_unix and tftp.unix. Same for mirage: Tftp_mirage and tftp.mirage.

> 3. Where's the code that generates / aggregates the package docs at
> http://mirage.github.io ?  It's pretty useful as-is but it would be
> even more useful if the front page index was sorted alphabetically
> (or, indeed, at all.. :)

this is an outdated page, which have been generated (at least) a year ago. We 
are still waiting for the new OCaml doc generator to improve that :-) A popular 
ocamldoc' style is Daniel's one. Could be enable by putting [3] in your doc 
directory and [4] in your myocamlbuild.ml.

[3]: https://github.com/samoht/assemblage/blob/master/doc/style.css
[4]: https://github.com/mirage/irmin/blob/master/myocamlbuild.ml#L643-646

> Finally, of course, any other commentary on the code in that repo is
> welcome-- whether as issues or just comments on style (or lack of it!)
> :)

It's usually better (for the doc outputs) to define separate module types. So 
instead of:

module Make(C:V1_LWT.CONSOLE)(FS:V1_LWT.KV_RO)(S:V1_LWT.STACKV4) : sig
  [blabla]
end

you could write:

module type S = sig
  [blabla + some abstract types]
end
module Make(C:V1_LWT.CONSOLE)(FS:V1_LWT.KV_RO)(S:V1_LWT.STACKV4): S with type 
[type constraints]

Sometimes the gain is not totally clear (as you have to define abstract types) 
but it usually makes the documentation is bit clearer.

Thomas
---

Here are a rough description of my workflow and random thoughts associated to 
it:

### Setup

Starting from scratch on a new machine, I need:

- `opam install ocp-indent tuareg merlin`
- Set-up `.emacs` manually (by copying my 
[dotfiles](https://github.com/samoht/dotfiles)]

What could be (or is) improving:
- `opam install user-setup` ? [need to test]
- `opam install opam-tools`   [todo]

### Create a new project

- copy _oasis from somewhere else
- copy basic alcotest skeleton from another project
- start writing code (first `.mli` and then `.ml`)
- generate _oasis autogen (Makefile, _tags, setup.ml, ...)
- create a repo on Github
- create an opam file
- copy ocaml-travisci-skeletons
- activate testing on TravisCI website
- edit Makefile to add version.ml generation
- edit Makefile to add gh-pages generation
- edit _tags to add nicer ocamldoc options
- init gh-pages manually, copy Daniel's css from somewhere else
- edit Makefile to add release scripts

What can be or is improving:

- `opam-publish` helps (but not fully)
- need more tool
- coverall (seems to work fine, but didn't try yet)

### Testing

- create a branch for new commits, open a PR to run TracisCI
- add tests

### Releasing

- bump version number
- regen `_oasis` auto-gen crap
- `make release` (when the project is well configured)
- look at TravisCI results on opam-repository
  - slow to get feedback (often 2h+ because of slow OSX workers on other builds)
  - usually fine, but sometime errors are not displayed properly (ex.
     cyclic dependency in my last PR)

What can be or is improving:

- need more precise feedback
- need faster feedback

### Maintenance

- online docs: `make gh-pages`, hosted on gh-pages

What can be or is improving:

- usual ocamldoc flows:
  - no cross-project references
  - missing module expansion

- need better integration with the workflow.
  - could be a post-hook script on TravisCI scripts (as for deployment of 
unikernels)
  - could also be a crawler bot who creates PR on projects
  - could also be centralized on opam docs website

> -- 
> Richard Mortier
> richard.mortier@xxxxxxxxxxxx
> 
> _______________________________________________
> MirageOS-devel mailing list
> MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
> http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel


_______________________________________________
MirageOS-devel mailing list
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel