Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006135OCamlOCaml documentationpublic2013-08-22 11:232014-09-30 00:20
ReporterHendrik Tews 
Assigned Towhitequark 
PriorityurgentSeverityminorReproducibilityalways
StatusassignedResolutionopen 
PlatformOSOS Version
Product Version4.01.0+beta/+rc 
Target Version4.02.1+devFixed in Version 
Summary0006135: Please document -ppx option
DescriptionLooking at the 4.01beta reference manual I cannot find -ppx!

Apart from including -ppx it would be nice to have some basic information about ppx commands (howto read/write the syntax tree, the type of the syntax tree), as well as a pointer to more extensive documentation.
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0010226)
gasche (developer)
2013-08-22 11:36

My personal hunch is that before we know what will be done with extension_points branch (eg. integrating it in time for a 4.02 release), there are relatively few legitimate uses of -ppx, and adding extension_points in the mix would probably require an extensive reformulation of the documentation if it exists. (There already is some documentation for extension_points specifically in http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/extension_points.txt?view=markup [^] ).

In particular, I think that using -ppx to overload the meaning of program fragments that already have a syntactic meaning in the existing OCaml language (as done in wmeyer's OMonad for experimentation purposes : http://danmey.org/omonad.html [^] ) is a bad practice that we should not encourage. The question is what other use cases remain without extension_points. There are definitely some ( it is used by an experimental version of Bisect http://bisect.x9c.fr/index.html [^] for example), but not as much as there could be in 4.02.

Of course more documentation is better than less, so if you or anyone feels motivated to write something (I guess the best thing to do for now is to look at the existing uses of -ppx to understand how to implement filters with it), I would be happy to have a look, provide feedback, and get something integrated in the manual if it's good.
(0010227)
doligez (administrator)
2013-08-22 21:47

Hmm. I spend a whole day making sure that every command line option is documented, both in the manual and in the man pages, for ocamlc, ocamlopt, and ocaml...

As for giving a detailed documentation of the AST types, I think like Gabriel that it's probably too early.
(0010235)
Hendrik Tews (reporter)
2013-08-23 11:43

OK, I didn't know that the extensions have not been merged yet.

Then I would suggest to briefly document -ppx with the calling convention and the data type, eg

-ppx <command> Run <command> as external filter on the
                  abstract syntax tree after parsing. The filter
                  is expected to read/write a marshaled ast
                  of type XXX on stdin/stdout. This option will
                  only get useful when extension points have been
                  implemented in one of the following releases.
(0012027)
shinwell (developer)
2014-08-20 09:48

Gabriel, what are we going to do about this? It's marked as target 4.02.0+dev.
(0012030)
doligez (administrator)
2014-08-20 19:09

> It's marked as target 4.02.0+dev.

That doesn't mean it must be done for 4.02.0, we can still postpone it. I talked to Alain in private, and he says we can (and should) document it after the release.
(0012036)
gasche (developer)
2014-08-21 08:37
edited on: 2014-08-21 08:37

I don't know -ppx well enough to write the documentation (should I reassign the issue?). If Alain can do it, that's very good; otherwise we may try to nicely ask Peter "whitequark" Zotov for help, as he's played with -ppx a lot in the last few months.

(0012038)
doligez (administrator)
2014-08-21 11:16

Alain is busy right now, so I'll release 4.02 without this documentation. It's still urgent but it can be written after the release.
(0012222)
doligez (administrator)
2014-09-28 00:26

Any chance of getting this documented before 4.02.1 (i.e. within one week)?
(0012224)
whitequark (developer)
2014-09-28 00:44

I'll send a PR within a few days. Should be quick enough for 4.02.1.
(0012255)
whitequark (developer)
2014-09-29 22:12

Ok, so, I took a stab at it today.

First, the build system of ocaml-manual is ... let's say it needs improvements. It is not friendly to contributors right now.

Why does it try to use an OCaml from ../release? Why does it not set LD_LIBRARY_PATH properly for dllunix.so to be found? As a result it does not work with system compiler, or without (matching) system compiler.

There's also multind.sty which is not present even in texlive-extra from Debian. However this is easier to fix.

Second, and more importantly, compiler-libs are currently missing from the manual (and manpages aren't build as well). I was going to add a reference to Ast_mapper to the description of -ppx but it's not there... I'll take a look at how hard it is to add this to the manual.
(0012256)
lpw25 (developer)
2014-09-30 00:17

> Second, and more importantly, compiler-libs are currently missing from the manual (and manpages aren't build as well). I was going to add a reference to Ast_mapper to the description of -ppx but it's not there... I'll take a look at how hard it is to add this to the manual.

I don't think we want to add compiler libs to the manual. They are not proper APIs and we make no guarantees about backwards-compatibility.
(0012257)
whitequark (developer)
2014-09-30 00:20

lpw25: But compiler-libs, at least the parsing/ part, is required in order to write any ppx code. Its stability notwithstanding, this is what people are going to use anyway. I see no point in excluding those for ideological reasons; if something, the parsing/ APIs should be tidied up even more and made proper APIs.

I did some initial work in https://github.com/ocaml/ocaml-manual/pull/5. [^] More work on OCaml repo itself is required, specifically:

  * Update manpages.
  * Install manpages for Ast_mapper &co.
  * Explain how to implement rewriters in a few words at the top of Ast_mapper.mli.

- Issue History
Date Modified Username Field Change
2013-08-22 11:23 Hendrik Tews New Issue
2013-08-22 11:36 gasche Note Added: 0010226
2013-08-22 21:47 doligez Note Added: 0010227
2013-08-22 21:47 doligez Status new => acknowledged
2013-08-22 21:47 doligez Target Version => later
2013-08-23 11:43 Hendrik Tews Note Added: 0010235
2013-09-12 15:59 doligez Target Version later => 4.02.0+dev
2014-08-18 20:20 doligez Priority normal => urgent
2014-08-20 09:48 shinwell Note Added: 0012027
2014-08-20 09:48 shinwell Assigned To => gasche
2014-08-20 09:48 shinwell Status acknowledged => assigned
2014-08-20 19:09 doligez Note Added: 0012030
2014-08-21 08:37 gasche Note Added: 0012036
2014-08-21 08:37 gasche Note Edited: 0012036 View Revisions
2014-08-21 11:16 doligez Note Added: 0012038
2014-08-21 11:16 doligez Target Version 4.02.0+dev => 4.02.1+dev
2014-09-04 00:25 doligez Target Version 4.02.1+dev => undecided
2014-09-23 17:34 doligez Target Version undecided => 4.02.1+dev
2014-09-24 16:07 gasche Assigned To gasche => whitequark
2014-09-28 00:26 doligez Note Added: 0012222
2014-09-28 00:44 whitequark Note Added: 0012224
2014-09-29 22:12 whitequark Note Added: 0012255
2014-09-30 00:17 lpw25 Note Added: 0012256
2014-09-30 00:20 whitequark Note Added: 0012257


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker