generating MELT documentation from MELT sources.

[Basile Starynkevitch <basile at starynkevitch dot net>]

Hello All

I am working on the MELT branch [& plugin]
http://gcc.gnu.org/wiki/MiddleEndLispTranslator

MELT provides a lispy domain specific language [& its runtime] to code
GCC extensions in. So a MELT source file *.melt (eg foo.melt) is
translated into a sequence of *.c files (eg foo.c & foo+01.c &
foo+02.c) which are themselves compiled into a MELT *.so module
(e.g. foo.so). So a MELT module is like a GCC plugin, except that it
goes thru the MELT runtime and has a different ABI.

I am understanding that the GCC runtime licence gives the same
permissions for MELT modules (which are dlopen-ed by the melt.so
plugin for GCC 4.5, or by the gcc-melt binaries when MELT is compiled
as a branch). This probably means that any *.melt file under GPLv3+ is
ok w.r.t GCC licences. My understanding is the the GPLv3+ licence is
principally on the human written *.melt files. Actually, the generated
C code also duplicates the licensing comment from the *.melt file. But
practically a MELT generated *.c file is useless -and not very human
understandable- if you don't have the *.melt source.

In practice, a MELT module can implement some GCC passes (coded in the
MELT language) and install them in the GCC pass tree. In addition, the
entire MELT language is implemented in MELT (and is bootstrapped, so
the subversion tree or any MELT source distribution contains not only
the *.melt files for the MELT translator, but also the generated
melt/generated/*.c files which are their translation to C).

The MELT branch has also a [very incomplete, but existing]
documentation. You could regenerate it (as usual, by make pdf) or you
can look at a previous version of it on
http://gcc.gnu.org/wiki/MELT%20tutorial?action=AttachFile&do=view&target=GCC-MELT--gcc-internals-snapshot.pdf
I am refering to that file when I speak of the "generated PDF file"
in this email.

The reference documentation is automatically generated (by a special
mode of MELT). You can look at the chapter 15 (pages 319 & following)
of the generated PDF file linked above. The documentation is generated
by parsing the MELT source files, in particular by using the :doc
annotations inside them (and by computing standard things, like
e.g. class hierarchy, some cross-referencing, etc..).

I find quite convenient the idea of generating reference documentation
by processing the *.melt source files. I would be very sad to have to
abandon this idea.

So my question is: is there any legal or licensing issues to generate
*.texi from *.melt files; the *.melt files are of course FSF
copyrighted GPLv3+ licensed, as code in every branch of GCC. The
*.texi files (at least those written by humans, including melt.texi
written by me) are of course FSF copyrighted & in my understanding
GFDLv1.2+ licenced, as every *.texi files inside GCC.

A typical example of MELT code containing documentation is available
in many places, but in particular in gcc/melt/warmelt-base.melt [and
many other *.melt files] of the MELT branch. For examples:





The primitive to ignore a value is coded as

  ################ near start of file warmelt-base.melt, near line 35

  ;; primitive to ignore a value
  (defprimitive ignore (v) :void
    :doc #{Ignore the value passed as argument. Useful to avoid translation warnings, or to force the type of a conditional. See $CTYPE_VOID.}#
    #{/*ignore*/(void)($v)}#)  

  ################ end of citation from warmelt-base.melt

The generated documentation appears in page 458 of the generated PDF
file [yes, the names are not alphabetically sorted, that is a bug in
the documentation generator]




The iterator on integers, whose occurrences are translated to simple
for($IX=$IMIN; $IX<=$IMAX; $IX++) loops

   ################ from file warmelt-base.melt near line 342
   ;;; citerator on integers
   (defciterator foreach_long_upto
     (:long imin imax)			;start formals
     eachlong				;state
     (:long ix)				;local formals
     :doc #{The $FOREACH_LONG_UPTO c-iterator provides the usual
   ascending integer iterator. Start formals are $IMIN, the minimum start
   integer, and $IMAX, le maximal ending integer. Local formal is $IX,
   the current index. The body is executed for each integer value $IX
   from $IMIN to $IMAX included.}#
     					;before expansion
   #{/*start $eachlong */
       long $eachlong#_min =  $imin;
       long $eachlong#_max = $imax;
       long $eachlong#_cur = 0;
       for ($eachlong#_cur = $eachlong#_min;
            $eachlong#_cur <= $eachlong#_max;
   	 $eachlong#_cur ++) {
   	    $ix = $eachlong#_cur;	    
   }#
    					;after expansion
      #{ } /*end eachlong */}#
   )
   ######################## end of citation from file warmelt-base.melt

The generated documentation appears page 494 of the PDF file.   







GCC passes are reified as MELT objects, instances of the following classes

  ################ from file warmelt-first.melt near line 641
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ;;;; ================ GCC compiler passes
  (defclass class_gcc_pass
    :predef CLASS_GCC_PASS
    :super class_named
    ;; keep the fields list in sync with melt-runtime.h FGCCPASS_*
    :fields (gccpass_gate			;closure for gate
  	   gccpass_exec			;closure for execution
  	   gccpass_data			;extra data
  	   ;;;; the following fields are mimicking their equivalent in
  	   ;;;; struct opt_pass of gcc/tree-pass.h
  	   ;;;;;; if it is a boxed integer, get the integer
  	   ;;;;;; if it is a string or a named, translate it
  	   ;;;;;; if it is a list or a tuple, make an OR mask of them
  	   gccpass_properties_required 
  	   gccpass_properties_provided
  	   gccpass_properties_destroyed
  	   gccpass_todo_flags_start
  	   gccpass_todo_flags_finish
  	   )
    :doc #{ The $CLASS_GCC_PASS is the super-class of GCC compiler
  passes descriptors, as provided in MELT. Once correctly instanciated,
  such a pass descriptor should be registered thru the
  $INSTALL_MELT_GCC_PASS primitive. Pass descriptors are named (be
  careful to give a unique unused name!). The $GCCPASS_GATE is the pass
  gate function. The $GCCPASS_EXEC is the pass execution function. The
  field $GCCPASS_DATA can be used for client data. The fields
  $GCCPASS_PROPERTIES_REQUIRED $GCCPASS_PROPERTIES_PROVIDED
  $GCCPASS_PROPERTIES_DESTROYED $GCCPASS_TODO_FLAGS_START
  $GCCPASS_TODO_FLAGS_FINISH are like their counterparts in C, and can
  be a boxed integer, a string or named [i.e. symbol], or a tuple or
  list of them.}# )

  (defclass class_gcc_gimple_pass
    :predef CLASS_GCC_GIMPLE_PASS
    :super class_gcc_pass
    :fields ( )
    :doc #{ The $CLASS_GCC_GIMPLE_PASS is for GCC gimple pass descriptors. }# 
  )

  ################ end of citation from  warmelt-first.melt

The generated documentation is page 338 & 339 of the PDF file. Notice
that the *.texi generator lists the fields inherited from
class_gcc_pass in the documentation of class_gcc_gimple_pass.






I hope there is no issues here, but I might have remembered in the
past some discussions somewhere about GFDLv1.2+ & GPLv3
incompatibility. I forgot the details so I hope to be wrong.


I am not a lawyer (and don't understand them), I never be one, and I
probably won't ask any lawyer for advice on this point. Don't tell me
to ask a lawyer. I probably won't (they scares me a lot, at least
those internal to my employer CEA; and I am not sure they understand
USA laws, since they are French lawyers.). So I am asking here:

So can I continue to generate part of the MELT documention in *.texi
form from the *.melt files?

[I insist that all the concerned material is inside the MELT branch so
is FSF copyrighted and follows the licensing habits of GCC; Of course
I never added any "legal" or "license" sentences except the usual GCC
notices; all the code & documentation has been written by me =
Basile.]



In particular, I will soon have an intern -Jeremie Salvucci, according
to his & mine understanding he got all the legal papers ok for GCC-
working with me on MELT, and I might want him to contribute to improve
the documentation generator, or improve the documentation itself
(notably by improving the :doc fields inside MELT source).

Regards.
-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***