From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id E5A277EEBF for ; Sat, 8 Aug 2015 00:47:29 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of gabriel.scherer@gmail.com) identity=pra; client-ip=209.85.213.174; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of gabriel.scherer@gmail.com designates 209.85.213.174 as permitted sender) identity=mailfrom; client-ip=209.85.213.174; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-ig0-f174.google.com) identity=helo; client-ip=209.85.213.174; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="postmaster@mail-ig0-f174.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: A0DEAQC7NMVVm67VVdFbhFgGgx7CCQKBMAdMAQEBAQEBEgEBAQEBBgsLCSEuhCQBAQMBEhEdARsPAgwBAwELBgMCBAc3AgIhAQERAQUBHAYTIod2AQMKCJpLjz+BLj4xiz+BbIJ5iyEKGScNV4RVAQEBAQEFAQEBAQEXAQUOi0GCT4I6B4JpgUMFlQiKcYFrkkOFZhIjgRcXhA48MYJMAQEB X-IPAS-Result: A0DEAQC7NMVVm67VVdFbhFgGgx7CCQKBMAdMAQEBAQEBEgEBAQEBBgsLCSEuhCQBAQMBEhEdARsPAgwBAwELBgMCBAc3AgIhAQERAQUBHAYTIod2AQMKCJpLjz+BLj4xiz+BbIJ5iyEKGScNV4RVAQEBAQEFAQEBAQEXAQUOi0GCT4I6B4JpgUMFlQiKcYFrkkOFZhIjgRcXhA48MYJMAQEB X-IronPort-AV: E=Sophos;i="5.15,631,1432591200"; d="scan'208";a="172998637" Received: from mail-ig0-f174.google.com ([209.85.213.174]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 08 Aug 2015 00:47:29 +0200 Received: by igfj19 with SMTP id j19so20758822igf.1 for ; Fri, 07 Aug 2015 15:47:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=AJByRG5IIrHgGQ08XssU/+fZBgNrmAt3p5naG4xvWp0=; b=C9p6ULHS7K2arJfeq/Pe3wejIW79r8b1aGcXLB5r6vSQHms19SzQ6a8zD4XFy7SnBj hUxqtUtUf7zUOy0ek+4nYn48gURcW7/IhmevdA9GjJEt3p7m/Ozzn6jH5qf81s8lFEnv pCUGFqk8zw5Ek/FJcKYLnhEocL+KG/ZzQTfBikzlmyTfbSbz56dLvnX+NXk4r/jIWGfj BiNb72ulEsI5n+d99e1ZYUfKu7dqRxgbpjGpvVYRNMk/4KFN+nbjlRRAREo3P1urIRfs 9cIHngalbGWldIgMxn3oLQWs4KJyNsVg/Fl5UvgkaayuiMOTMqj2cOnklQjEeWTYbdcY MmlQ== X-Received: by 10.50.103.71 with SMTP id fu7mr527068igb.38.1438987648184; Fri, 07 Aug 2015 15:47:28 -0700 (PDT) MIME-Version: 1.0 Received: by 10.79.68.132 with HTTP; Fri, 7 Aug 2015 15:46:48 -0700 (PDT) In-Reply-To: References: From: Gabriel Scherer Date: Sat, 8 Aug 2015 00:46:48 +0200 Message-ID: To: Leonid Rozenberg Cc: Caml List Content-Type: multipart/alternative; boundary=047d7b2e11e79b3a5e051cc06b99 Subject: Re: [Caml-list] Learning about compiler-libs --047d7b2e11e79b3a5e051cc06b99 Content-Type: text/plain; charset=UTF-8 The short answer is: no, there is no documentation. The long answer: compiler-libs was made available following the demand of expert users, that were already familiar with the compiler codebase, willing to reuse its internals to develop tooling around the language. Nobody had the time back then to contribute a comprehensive documentation, or even to define a reasonable API subset to expose (so basically everything is exposed). Finally, there is no guarantee of API compatibility across OCaml versions, so reusing this makes you tightly coupled to the compiler evolution. Documentation emerges slowly under the form of blog posts, discussions, and evolution of the codebase. In particular, over the course of his work on -ppx, Alain Frisch enriched parsing/parsetree.mli with invaluable comments describing the mapping between concrete and abstract syntax. Everyone is warmly welcome to contribute such improvements to the (codebase) documentation. On Sat, Aug 8, 2015 at 12:25 AM, Leonid Rozenberg wrote: > Are there any resources besides the couple of blog posts and reading the > source? > > I found this surprising: > > OCaml version 4.02.1 > > # #use "topfind" ;; > - : unit = () > Findlib has been successfully loaded. Additional directives: > #require "package";; to load a package > #list;; to list the available packages > #camlp4o;; to load camlp4 (standard syntax) > #camlp4r;; to load camlp4 (revised syntax) > #predicates "p,q,...";; to set these predicates > Topfind.reset();; to force that packages will be reloaded > #thread;; to enable threads > > - : unit = () > # #require "compiler-libs.toplevel" ;; > /Users/leonidrozenberg/.opam/4.02.1/lib/ocaml/compiler-libs: added to > search path > /Users/leonidrozenberg/.opam/4.02.1/lib/ocaml/compiler-libs/ocamlcommon.cma: > loaded > /Users/leonidrozenberg/.opam/4.02.1/lib/ocaml/compiler-libs/ocamlbytecomp.cma: > loaded > /Users/leonidrozenberg/.opam/4.02.1/lib/ocaml/compiler-libs/ocamltoplevel.cma: > loaded > # let a x = x + 1 ;; > >> Fatal error: a unbound at toplevel > Fatal error: exception Misc.Fatal_error > --047d7b2e11e79b3a5e051cc06b99 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
The short answer is: no, there is no documentati= on.

The long answer: compiler-libs was made available followin= g the demand of expert users, that were already familiar with the compiler = codebase, willing to reuse its internals to develop tooling around the lang= uage. Nobody had the time back then to contribute a comprehensive documenta= tion, or even to define a reasonable API subset to expose (so basically eve= rything is exposed). Finally, there is no guarantee of API compatibility ac= ross OCaml versions, so reusing this makes you tightly coupled to the compi= ler evolution.

Documentation emerges slowly under the form of = blog posts, discussions, and evolution of the codebase. In particular, over= the course of his work on -ppx, Alain Frisch enriched parsing/parsetree.ml= i with invaluable comments describing the mapping between concrete and abst= ract syntax. Everyone is warmly welcome to contribute such improvements to = the (codebase) documentation.

On Sat, Aug 8, 2015 at 12:25 AM, Leonid Rozenberg <l= eonidr@gmail.com> wrote:
Are there any resources besides the couple of blog post= s and reading the source?

I found this surprising:

=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 OCaml version = 4.02.1

# #use "topfind" ;;
- : unit =3D ()
Findlib h= as been successfully loaded. Additional directives:
=C2=A0 #require &quo= t;package";;=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 to load a package
=C2=A0= #list;;=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 to list the available packages=C2=A0 #camlp4o;;=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 to load camlp4 (standard syntax)
= =C2=A0 #camlp4r;;=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 to load camlp4 (revised syntax)
=C2=A0= #predicates "p,q,...";;=C2=A0=C2=A0 to set these predicates
= =C2=A0 Topfind.reset();;=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 to= force that packages will be reloaded
=C2=A0 #thread;;=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0 to enable threads

- : unit =3D ()
# #require "compiler-l= ibs.toplevel" ;;
/Users/leonidrozenberg/.opam/4.02.1/lib/ocaml/comp= iler-libs: added to search path
/Users/leonidrozenberg/.opam/4.02.1/lib/= ocaml/compiler-libs/ocamlcommon.cma: loaded
/Users/leonidrozenberg/.opam= /4.02.1/lib/ocaml/compiler-libs/ocamlbytecomp.cma: loaded
/Users/leonidr= ozenberg/.opam/4.02.1/lib/ocaml/compiler-libs/ocamltoplevel.cma: loaded
= # let a x =3D x + 1 ;;
>> Fatal error: a unbound at toplevel
Fa= tal error: exception Misc.Fatal_error

--047d7b2e11e79b3a5e051cc06b99--