[m-rev.] for review: Allow external files to be included in foreign_decl and foreign_code.

[Peter Wang]

On Mon, 17 Mar 2014 13:48:27 +1100 (EST), Julien Fischer <jfischer at opturion.com> wrote:
> 
> Hi Peter,
> 
> On Mon, 17 Mar 2014, Peter Wang wrote:
> 
> > On Mon, 17 Mar 2014 11:44:29 +1100 (EST), Julien Fischer <jfischer at opturion.com> wrote:
> >>
> >> Why is this feature an implementation-dependent extension rather than
> >> just a normal part of the foreign language interface?
> >
> > The path syntax issues gave me pause.  I don't think platform-dependent
> > stuff belongs in the language proper.
> 
> IMO, it's okay for include_file to be in the language proper even though
> the path part will be platform dependent (it's a bit difficult to avoid
> that particular platform dependency).

It doesn't really matter but I'll call it an extension, at least for now.
For ease of reading we can document it alongside foreign_decl/code
(see below).

> I am slightly worried that hardcoding the paths will mean that Mercury
> programs do not build portably -- what will presuambly be the common
> case, i.e. where the included file is in the same directory as the
> module that includes it, should alway work though (modulo the issues you
> mention with filename encoding below).  Would it be worth having an
> option for the compiler, for example --foreign-include-dir, that allowed
> search directories for included files to be specified?  That way, the
> platform-dependent bits could (mostly) be dealt with in configure
> scripts, makefiles etc.

Maybe, if it comes up.

There is a potential for confusion if you run

    mmc --make foo --foreign-include-dir dirA
    mmc --make foo --foreign-include-dir dirB

It wouldn't rebuild foo in the second run because foo.module_dep still
refers to the file that was logically included in the first run.  It's
not a unique problem to --foreign-include-dir, though, and --track-flags
would help.

> It would be worth adding a note about the encoding issue  to the
> documentation of this feature.

I'm not sure what it should say.

This diff is for review.

Peter

diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index 52fa02f..b1da7e2 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -6278,6 +6278,10 @@ fair search rule; and so forth.
 * Adding foreign declarations::        How to add declarations of
   				       entities in other programming
 				       languages.
+* Declaring Mercury exports to other modules::
+                                       How to call Mercury procedures from a
+                                       different programming language in
+                                       another module.
 * Adding foreign definitions::         How to add definitions of
   				       entities in other programming
 				       languages.
@@ -7362,6 +7366,31 @@ you can use the following variant of the declaration:
 Note: currently only the C and Erlang backends support this variant
 of the @samp{pragma foreign_decl} declaration.
 
+The Melbourne Mercury implementation additionally supports the forms
+
+ at example
+:- pragma foreign_decl("@var{Lang}", include_file("@var{Path}")).
+:- pragma foreign_decl("@var{Lang}", local, include_file("@var{Path}")).
+ at end example
+
+These have the same effects as the standard forms except that the
+contents of the file referenced by @var{Path} are included in place of
+the string literal in the last argument, without further interpretation.
+ at var{Path} may be an absolute path to a file, or a path to a file relative
+to the directory that contains the source file of the module containing the
+declaration. The interpretation of the path is platform-dependent.
+The filesystem character set and encoding may differ from the Mercury
+source file (which must be UTF-8); the behaviour of the compiler depends
+on the behaviour of standard library io module.
+
+ at samp{mmc --make} and @samp{mmake} treat included files as dependencies
+of the module.
+
+ at c -----------------------------------------------------------------------
+
+ at node Declaring Mercury exports to other modules
+ at section Declaring Mercury exports to other modules
+
 The declarations for Mercury predicates or functions exported to a 
 foreign language using a @samp{pragma foreign_export} declaration
 are visible to foreign code in a @samp{pragma foreign_code} or
@@ -7405,6 +7434,8 @@ Note that the Melbourne Mercury implementation often implicitly inserts
 @samp{pragma foreign_import_module} declarations should always be explicitly
 included if needed.
 
+ at c -----------------------------------------------------------------------
+
 @node Adding foreign definitions
 @section Adding foreign definitions
 
@@ -7426,6 +7457,25 @@ Entities declared in @samp{pragma foreign_code} declarations are
 visible in @samp{pragma foreign_proc} declarations that specify the same
 foreign language and occur in the same Mercury module.
 
+The Melbourne Mercury implementation additionally supports the form
+
+ at example
+:- pragma foreign_code("@var{Lang}", include_file("@var{Path}")).
+ at end example
+
+This has the same effect as the standard form except that the
+contents of the file referenced by @var{Path} are included in place of
+the string literal in the last argument, without further interpretation.
+ at var{Path} may be an absolute path to a file, or a path to a file relative
+to the directory that contains the source file of the module containing the
+declaration. The interpretation of the path is platform-dependent.
+The filesystem character set and encoding may differ from the Mercury
+source file (which must be UTF-8); the behaviour of the compiler depends
+on the behaviour of standard library io module.
+
+ at samp{mmc --make} and @samp{mmake} treat included files as dependencies
+of the module.
+
 @c -----------------------------------------------------------------------
 
 @node Language specific bindings