[m-rev.] for review: end-user documentation for Erlang backend
Peter Wang
wangp at students.csse.unimelb.edu.au
Wed Jul 18 13:32:25 AEST 2007
Estimated hours taken: 6
Branches: main
Add more documentation for the Erlang backend.
Make it possible to configure and install the Erlang backend without too
much manual tweaking.
NEWS:
Mention the Erlang backend.
README.Erlang:
Add installation and other notes for Erlang.
doc/reference_manual.texi:
doc/user_guide.texi:
Add documentation for Erlang.
aclocal.m4:
configure.in:
Check that the bootstrap compiler knows about the
builtin_compound_{eq,lt} builtins, and understands
--erlang-native-code.
Make configure check for Erlang tools.
Add configure --enable-erlang-grade option. Erlang support
is disabled by default.
scripts/Mercury.config.in:
Add `--erlang-compiler <erl>' and `--erlang-interpreter <erlc>'
options to be set by configure.
analysis/ANALYSIS_FLAGS.in:
compiler/COMP_FLAGS.in:
mdbcomp/MDBCOMP_FLAGS.in:
Add `--erlang-include-directory <dir>/Mercury/hrls' options so that
the compiler can find Erlang header files from other subdirectories.
compiler/Mercury.options:
library/Mercury.options:
Work around bugs in the HiPE compiler when compiling two modules.
Delete the workaround that was necessary while bootstrapping
builtin_compound_{eq,lt}.
compiler/options_file.m:
Support ERLANG_FLAGS, EXTRA_ERLANG_FLAGS variables in options files to
be the same as passing --erlang-flags.
browser/Mmakefile:
compiler/Mmakefile:
deep_profiler/Mmakefile:
library/Mmakefile:
mdbcomp/Mmakefile:
profiler/Mmakefile:
runtime/Mmakefile:
slice/Mmakefile:
trace/Mmakefile:
Make the build system do the same things in the Erlang grade as for
the IL and Java grades.
scripts/final_grade_options.sh-subr:
scripts/parse_grade_options.sh-subr:
Make these scripts know about the erlang grade so that parts of the
build system won't abort on seeing it.
Index: NEWS
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/NEWS,v
retrieving revision 1.469
diff -u -r1.469 NEWS
--- NEWS 14 Jul 2007 02:32:29 -0000 1.469
+++ NEWS 18 Jul 2007 02:37:33 -0000
@@ -177,6 +177,8 @@
Changes to the Mercury compiler:
+* We have added an Erlang back-end.
+
* In parallel grades we now support thread-local trailing.
* The compiler now issues a warning when an inst declaration is not
@@ -278,6 +280,14 @@
Changes to the Mercury compiler:
+* There's a new back-end that targets Erlang.
+
+ Compiler support for this new back-end is mostly complete,
+ but large parts of the standard library are still not yet
+ implemented for this new port.
+
+ For more details, see the README.Erlang.
+
* The compiler now issues a warning when an inst declaration isn't
consistent with any of the types in scope.
Index: README.Erlang
===================================================================
RCS file: README.Erlang
diff -N README.Erlang
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ README.Erlang 18 Jul 2007 02:37:33 -0000
@@ -0,0 +1,230 @@
+-----------------------------------------------------------------------------
+
+INTRODUCTION
+
+This release of Mercury contains a port to Erlang. The Mercury
+compiler will generate Erlang source code that can be compiled into
+bytecode or native code suitable for running in the Erlang runtime
+system.
+
+The port is incomplete. Large parts of the Mercury standard library
+are not yet implemented. Some RTTI related features are incompletely
+or incorrectly implemented.
+
+PREREQUISITES
+
+In order to try this system you will need
+
+ - The Erlang/OTP distribution, which is open source and can be
+ downloaded from
+ <http://www.erlang.org/download.html>
+
+ - The Mercury source distribution. See below for installation
+ instructions.
+
+ If you're reading this file from somewhere other than the
+ Mercury distribution, try the Mercury homepage at
+ <http://www.mercury.csse.unimelb.edu.au>
+
+ - An installed Mercury compiler. You must use `mmc --make' to
+ install the standard library for Erlang. See below.
+
+ - A Unix-like environment. The Erlang support has not been
+ tested on Windows, but you will need a shell script
+ interpreter.
+
+WARNING
+
+Please note that the Erlang backend is still an experimental feature.
+
+-----------------------------------------------------------------------------
+
+INSTALLATION
+
+The Mercury compiler itself can be installed with Erlang support as
+usual, but the standard library can currently only be built for the
+Erlang using `mmc --make'. Therefore you must already have an
+installed Mercury compiler available.
+
+Invoke configure with the option `--enable-erlang-grade' in order to
+enable Erlang support. Make sure it was detected properly by running:
+
+ mmake echo_libgrades
+
+Then run:
+
+ mmake --use-mmc-make install
+or
+ mmake --use-mmc-make install LIBGRADES=erlang
+
+For better performance you will need to add the following line to
+Mmake.params before installing:
+
+ EXTRA_MCFLAGS += --erlang-native-code
+
+-----------------------------------------------------------------------------
+
+THE ERLANG GRADE
+
+The Mercury compiler currently supports the grade `erlang'.
+The erlang grade is enabled by using any of the options
+`--grade erlang', `--target erlang', or just `--erlang',
+in combination with `mmc --make'. Mmake does _not_ currently support
+the erlang grade.
+
+To run a Mercury program using the erlang grade, you need to build the
+Mercury library in the erlang grade, using the Mercury source distribution.
+
+You can now build programs such as hello.m or calculator.m in the samples
+directory.
+
+ cd samples
+ mmc --make --erlang hello
+
+Now you can run hello
+
+ ./hello
+
+Note that hello is a simple shell script that starts the Erlang
+runtime system. The actual object files will be stored in the Mercury
+subdirectory, in `beams'.
+
+-----------------------------------------------------------------------------
+
+USING ERLANG
+
+The Mercury standard library has not been fully ported to Erlang yet.
+The use of unimplemented procedures will result in a run-time error,
+with a message such as "Sorry, not implemented: foreign code for this
+function", and a stack trace.
+
+If you find missing functionality, you can interface to Erlang using
+Mercury's foreign language interface.
+
+For more information about the foreign language interface, see the Mercury
+Language Reference Manual, which you can find at:
+
+ <http://www.mercury.csse.unimelb.edu.au/information/documentation.html>
+
+-----------------------------------------------------------------------------
+
+PERFORMANCE NOTES
+
+The Erlang code generated by the Mercury compiler is designed to be compiled
+to native code, using the HiPE compiler. The Erlang bytecode compiler does
+not recognise static data structures so some run-time type information can
+get created repeatedly again at runtime. HiPE treats static data structures
+specially so does not have this problem.
+
+You can pass the `--erlang-native-code' option to mmc to use HiPE to compile
+.erl files to .beam files. It is recommended to add this flag to
+Mmake.params before installing the standard library.
+
+The need to support user-defined equality and comparison predicates can
+cause significant slowdowns, even when they are unused. This problem
+usually exists when a type contains an abstract type in its definition. The
+compiler does not know if an abstract type has user-defined equality or not,
+so makes a conservative assumption. Enabling intermodule optimisation gives
+the compiler enough information to avoid this problem.
+
+-----------------------------------------------------------------------------
+
+DIFFERENCES FROM OTHER BACKENDS
+
+* Discriminated union values are ordered according to Erlang conventions
+ (e.g. alphabetically) instead of according to the order that data
+ constructors appear in the type definition.
+
+* Some legal Mercury code making use of partial instantiation will be
+ rejected when compiling to Erlang (you will get a compiler abort).
+ An example is:
+
+ foo(Xs) :-
+ ( Xs = []
+ ; Xs = [1 | _]
+ ),
+ ( Xs = []
+ ; Xs = [_ | []]
+ ).
+
+-----------------------------------------------------------------------------
+
+RESOURCES
+
+You might find the following pages useful:
+
+ <http://www.mercury.csse.unimelb.edu.au/backends.html>
+
+ <http://www.mercury.csse.unimelb.edu.au/information/documentation.html>
+
+-----------------------------------------------------------------------------
+
+FREQUENTLY ASKED QUESTIONS (FAQS)
+
+Q. What are the advantages of using the Erlang back-end?
+
+A. The goal is to take advantage of the Erlang implementation for writing
+ scalable and reliable server programs, which can be distributed over
+ multiple machines and, possibly, updated at run-time.
+
+
+Q. What version of Erlang should I be using?
+
+A. We have tested with Erlang/OTP R11-R3 and up.
+
+
+Q. What features are not yet implemented for the Erlang back-end?
+
+A. The following language features are not supported and will not be:
+
+ trailing
+ solver types
+
+ The following implementation features are not supported:
+
+ Mercury-level debugging
+ Mercury-level profiling
+
+ The following standard library modules are completely unimplemented:
+
+ benchmarking
+ bit_buffer
+ bitmap
+ construct
+ deconstruct
+ dir
+ thread
+ thread.semaphore
+ time
+ version_array
+
+ In addition, many modules are incompletely implemented or have placeholder
+ implementations.
+
+Q. So how do I enable Erlang-level debugging?
+
+A. With great difficulty. One way is to copy or symlink all the .erl and
+ .hrl files used by the program, including those of the standard library,
+ into a single directory. Then build the .beam files with debugging
+ enabled, e.g.
+
+ erlc +debug_info *.erl
+
+ Start up the Erlang runtime system and the debugger:
+
+ % erl
+ ...
+ 1> debugger:start().
+
+ In the debugger, select Module > Interpret... and choose the modules to
+ interpret (probably "All"). At the erl prompt, the program can be started
+ like so:
+
+ % hello:mercury__main_wrapper().
+
+ To run it a second time you may need to call `main_2_p_0' instead.
+
+ For more information, see the documentation for erlc and the Erlang
+ debugger.
+
+-----------------------------------------------------------------------------
Index: aclocal.m4
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/aclocal.m4,v
retrieving revision 1.26
diff -u -r1.26 aclocal.m4
--- aclocal.m4 14 Jul 2007 02:32:30 -0000 1.26
+++ aclocal.m4 18 Jul 2007 02:37:33 -0000
@@ -351,3 +351,22 @@
])
#-----------------------------------------------------------------------------#
+#
+# Erlang configuration
+#
+AC_DEFUN(MERCURY_CHECK_ERLANG,
+[
+AC_ERLANG_PATH_ERLC
+AC_ERLANG_PATH_ERL
+
+if test "$ERLC" != "" -a "$ERL" != ""; then
+ mercury_cv_erlang="yes"
+else
+ mercury_cv_erlang="no"
+fi
+
+AC_SUBST(ERLC)
+AC_SUBST(ERL)
+])
+
+#-----------------------------------------------------------------------------#
Index: configure.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/configure.in,v
retrieving revision 1.494
diff -u -r1.494 configure.in
--- configure.in 12 Jul 2007 07:49:30 -0000 1.494
+++ configure.in 18 Jul 2007 02:37:33 -0000
@@ -321,6 +321,8 @@
--halt-at-warn \
--trace-io-builtins-2006-08-14 \
$link_static_opt conftest \
+ --compound-compare-builtins-2007-07-09 \
+ --erlang-native-code \
</dev/null >&AC_FD_CC 2>&1 &&
test "`./conftest 2>&1 | tr -d '\015'`" = "Hello, world" &&
# Test for the --record-term-sizes-as-words option.
@@ -933,6 +935,12 @@
MERCURY_CHECK_JAVA
#-----------------------------------------------------------------------------#
+# Erlang configuration
+#
+
+MERCURY_CHECK_ERLANG
+
+#-----------------------------------------------------------------------------#
mercury_check_for_functions () {
for mercury_cv_func in "$@"
@@ -2909,6 +2917,12 @@
AC_HELP_STRING([--enable-java-grade], [install the Java grade]),
enable_java_grade="$enableval",enable_java_grade=no)
+# We don't enable the Erlang grades by default because it is still
+# experimental and it requires mmc --make to install.
+AC_ARG_ENABLE(erlang-grade,
+ AC_HELP_STRING([--enable-erlang-grade], [install the Erlang grade]),
+ enable_erlang_grade="$enableval",enable_erlang_grade=no)
+
AC_ARG_ENABLE(libgrades,
AC_HELP_STRING([--enable-libgrades=...],
[install exactly the given versions of the library.
@@ -2930,6 +2944,7 @@
enable_par_grades=no
enable_dotnet_grades=no
enable_java_grade=no
+ enable_erlang_grade=no
fi
#-----------------------------------------------------------------------------#
@@ -3122,6 +3137,12 @@
LIBGRADES="$LIBGRADES java"
fi
+# add Erlang back-end grade, if Erlang is installed
+if test $mercury_cv_erlang = yes -a "$enable_erlang_grade" = yes
+then
+ LIBGRADES="$LIBGRADES erlang"
+fi
+
# Allow the user to override the default list of library grades
if test "$enable_libgrades_given" = no -a -f .enable_lib_grades ; then
Index: analysis/ANALYSIS_FLAGS.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/analysis/ANALYSIS_FLAGS.in,v
retrieving revision 1.2
diff -u -r1.2 ANALYSIS_FLAGS.in
--- analysis/ANALYSIS_FLAGS.in 12 Jan 2006 07:07:27 -0000 1.2
+++ analysis/ANALYSIS_FLAGS.in 18 Jul 2007 02:37:33 -0000
@@ -17,6 +17,9 @@
--c-include-directory ../browser/Mercury/mihs
--c-include-directory ../trace
--c-include-directory ../analysis
+--erlang-include-directory ../library/Mercury/hrls
+--erlang-include-directory ../mdbcomp/Mercury/hrls
+--erlang-include-directory ../analysis/Mercury/hrls
-L../boehm_gc
-L../runtime
-L../library
Index: browser/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/browser/Mmakefile,v
retrieving revision 1.51
diff -u -r1.51 Mmakefile
--- browser/Mmakefile 8 Jan 2007 07:07:04 -0000 1.51
+++ browser/Mmakefile 18 Jul 2007 02:37:33 -0000
@@ -96,11 +96,11 @@
#-----------------------------------------------------------------------------#
-# The IL and Java implementations of the standard library are not yet complete,
-# so we need to pass `--allow-stubs' to get them to compile.
+# The IL, Java, Erlang implementations of the standard library are not yet
+# complete, so we need to pass `--allow-stubs' to get them to compile.
# Since the standard library is compiled with `--halt-at-warn',
# we also need `--no-warn-stubs'.
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
MCFLAGS += --allow-stubs --no-warn-stubs
endif
@@ -276,9 +276,9 @@
mkdir -p $(INSTALL_GRADE_MODULE_DIR)
[ -d $(INSTALL_MERC_LIB_DIR) ] || mkdir -p $(INSTALL_MERC_LIB_DIR)
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
-# there is no browser in the .NET and Java backends
+# there is no browser in the .NET, Java, Erlang backends
.PHONY: install_init
install_init:
Index: compiler/COMP_FLAGS.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/COMP_FLAGS.in,v
retrieving revision 1.3
diff -u -r1.3 COMP_FLAGS.in
--- compiler/COMP_FLAGS.in 12 Sep 2006 04:10:56 -0000 1.3
+++ compiler/COMP_FLAGS.in 18 Jul 2007 02:37:33 -0000
@@ -19,5 +19,8 @@
--c-include-directory ../trace
--c-include-directory ../analysis
--c-include-directory ../analysis/Mercury/mihs
+--erlang-include-directory ../library/Mercury/hrls
+--erlang-include-directory ../mdbcomp/Mercury/hrls
+--erlang-include-directory ../analysis/Mercury/hrls
--no-main
--config-file ../scripts/Mercury.config.bootstrap
Index: compiler/Mercury.options
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/Mercury.options,v
retrieving revision 1.30
diff -u -r1.30 Mercury.options
--- compiler/Mercury.options 30 May 2007 07:11:09 -0000 1.30
+++ compiler/Mercury.options 18 Jul 2007 02:37:33 -0000
@@ -52,6 +52,9 @@
MCFLAGS-mode_robdd.tfeirn = -O3
MCFLAGS-mode_robdd.implications = -O0
+# Work around a problem in the HiPE compiler (as of Erlang R11B5).
+MCFLAGS-libs.options += --erlang-switch-on-strings-as-atoms
+
# The c_code in the module gcc.m needs the header files from the GNU C
# distribution. Note that we need to compile these with
# -DMR_NO_BACKWARDS_COMPAT, because otherwise there are name
Index: compiler/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/Mmakefile,v
retrieving revision 1.92
diff -u -r1.92 Mmakefile
--- compiler/Mmakefile 15 Jun 2007 15:49:33 -0000 1.92
+++ compiler/Mmakefile 18 Jul 2007 02:37:33 -0000
@@ -211,7 +211,7 @@
# (We used to just build mlds_to_gcc.err, but that caused bootstrapping problems
# with the source distribution; using the .c files is little more robust.)
-ifeq ("$(filter il% java%,$(GRADE))","")
+ifeq ("$(filter il% java% erlang%,$(GRADE))","")
.PHONY: depend
depend: COMP_FLAGS mlds_to_gcc.depend
Index: compiler/options_file.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/options_file.m,v
retrieving revision 1.45
diff -u -r1.45 options_file.m
--- compiler/options_file.m 14 Jul 2007 02:32:48 -0000 1.45
+++ compiler/options_file.m 18 Jul 2007 02:37:33 -0000
@@ -874,6 +874,7 @@
; java_flags
; ilasm_flags
; csharp_flags
+ ; erlang_flags
; ml_objs
; ml_libs
; ld_flags
@@ -900,7 +901,8 @@
options_variable_types =
[grade_flags, linkage, mercury_linkage, lib_grades, lib_linkages,
stdlib_dir, config_dir, mmc_flags, c_flags, java_flags, ilasm_flags,
- csharp_flags, ml_objs, lib_dirs, ld_flags, ld_libflags,
+ csharp_flags, erlang_flags,
+ ml_objs, lib_dirs, ld_flags, ld_libflags,
libraries, ml_libs, c2init_args, install_prefix].
:- func options_variable_name(options_variable_type) = string.
@@ -911,6 +913,7 @@
options_variable_name(java_flags) = "JAVACFLAGS".
options_variable_name(ilasm_flags) = "MS_ILASM_FLAGS".
options_variable_name(csharp_flags) = "MS_CSC_FLAGS".
+options_variable_name(erlang_flags) = "ERLANG_FLAGS".
options_variable_name(ml_objs) = "MLOBJS".
options_variable_name(ml_libs) = "MLLIBS".
options_variable_name(ld_flags) = "LDFLAGS".
@@ -934,6 +937,7 @@
options_variable_type_is_target_specific(java_flags) = yes.
options_variable_type_is_target_specific(ilasm_flags) = yes.
options_variable_type_is_target_specific(csharp_flags) = yes.
+options_variable_type_is_target_specific(erlang_flags) = yes.
options_variable_type_is_target_specific(ml_objs) = yes.
options_variable_type_is_target_specific(ml_libs) = yes.
options_variable_type_is_target_specific(ld_flags) = yes.
@@ -992,6 +996,7 @@
mmc_option_type(java_flags) = option([], "--java-flag").
mmc_option_type(ilasm_flags) = option([], "--ilasm-flag").
mmc_option_type(csharp_flags) = option([], "--csharp-flag").
+mmc_option_type(erlang_flags) = option([], "--erlang-flag").
mmc_option_type(ml_objs) = option([], "--link-object").
mmc_option_type(ml_libs) = mmc_flags.
mmc_option_type(ld_flags) = option([], "--ld-flag").
Index: deep_profiler/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/deep_profiler/Mmakefile,v
retrieving revision 1.20
diff -u -r1.20 Mmakefile
--- deep_profiler/Mmakefile 21 Nov 2006 03:08:38 -0000 1.20
+++ deep_profiler/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -64,7 +64,7 @@
# Add some additional dependencies, so that Mmake knows to remake the
# profiler if one of the libraries changes.
-ifeq ("$(filter il% java%,$(GRADE))","")
+ifeq ("$(filter il% java% erlang%,$(GRADE))","")
mdprof_cgi: $(RUNTIME_DIR)/lib$(RT_LIB_NAME).$A
mdprof_cgi: $(LIBRARY_DIR)/lib$(STD_LIB_NAME).$A
mdprof_test: $(RUNTIME_DIR)/lib$(RT_LIB_NAME).$A
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.398
diff -u -r1.398 reference_manual.texi
--- doc/reference_manual.texi 14 Jul 2007 02:32:59 -0000 1.398
+++ doc/reference_manual.texi 18 Jul 2007 02:37:34 -0000
@@ -4756,7 +4756,7 @@
@samp{initialize} is also allowed as a synonym for @samp{initialise}.
Note: @samp{initialise} declarations are currently only supported on
-the C backends.
+the C and Erlang backends.
@node Module finalisation
@section Module finalisation
@@ -4797,7 +4797,7 @@
@samp{finalize} is also allowed as a synonym for @samp{finalise}.
Note: @samp{finalise} declarations are currently only supported on
-the C backends.
+the C and Erlang backends.
@node Module-local mutable variables
@section Module-local mutable variables
@@ -4928,8 +4928,7 @@
specified in a @samp{initialise} directive.
Note: @samp{mutable} declarations are currently only supported on
-the C backends.
- at c and Erlang backends
+the C and Erlang backends.
@node Type classes
@chapter Type classes
@@ -6579,6 +6578,7 @@
* C data passing conventions ::
* IL and C# data passing conventions ::
* Java data passing conventions ::
+* Erlang data passing conventions ::
@end menu
@node C data passing conventions
@@ -6776,6 +6776,51 @@
and in Java modifications to mutable state are done via side effects,
rather than argument passing.)
+ at node Erlang data passing conventions
+ at subsection Erlang data passing conventions
+
+The Mercury types @code{int}, @code{float} and @code{char}
+are mapped to Erlang integers, floats and integers respectively.
+A Mercury @code{string} is represented as a list of integers in Erlang.
+
+Mercury variables whose type is a Mercury discriminated union type
+will be passed as an Erlang tuple with the first element of the tuple
+being an Erlang atom named after the Mercury data constructor.
+
+Mercury variables whose type is a Mercury equivalence type
+will be passed as the representation of the right hand side of the
+equivalence type.
+
+This mapping is subject to change and you should try to avoid writing
+code that relies heavily upon a particular representation of Mercury
+terms.
+
+Arguments of dummy types, e.g. @samp{io.state}, are represented by the
+atom @samp{false} when necessary. They are not passed to and from
+calls to monomorphic procedures.
+
+Mercury arguments declared with input modes are passed by value to the
+corresponding Erlang function.
+
+The result of an Erlang function depends on the determinism of the
+Mercury procedure that it was derived from. Procedures which succeed
+exactly once and have a single output variable return the single value
+directly. Procedures which succeed exactly once and have zero or two
+or more output variables return a tuple of those output variables in
+order.
+
+Procedures which are semideterministic return, on success, a tuple of
+the variables with output modes (including when the number of output
+variables is one). On failure they return the Erlang atom
+ at samp{fail}.
+
+Procedures which are nondeterministic take as a final argument a
+success continuation. This is an function which has an input variable
+for each variable of the Mercury procedure with an output mode. For
+each solution, the success continuation with the values of those
+output variables. When there are no more solutions the Erlang
+function returns with an undefined value.
+
@c -----------------------------------------------------------------------
@node Using foreign types from Mercury
@@ -6903,7 +6948,7 @@
:- pragma foreign_decl("@var{Lang}", local, @var{DeclCode}).
@end example
-Note: currently only the C backends support this variant
+Note: currently only the C and Erlang backends support this variant
of the @samp{pragma foreign_decl} declaration.
The declarations for Mercury predicates or functions exported to a
@@ -6976,6 +7021,7 @@
* Interfacing with C# :: How to write code to interface with C#
* Interfacing with IL :: How to write code to interface with IL
* Interfacing with Java :: How to write code to interface with Java
+* Interfacing with Erlang :: How to write code to interface with Erlang
@end menu
All Mercury implementations should support interfacing with C.
@@ -7004,6 +7050,9 @@
@item @samp{Java}
Use the string @code{"Java"} to set the foreign language to Java.
+ at item @samp{Erlang}
+Use the string @code{"Erlang"} to set the foreign language to Erlang.
+
@end table
@c -----------------------------------------------------------------------
@@ -7704,6 +7753,146 @@
@c ----------------------------------------------------------------------------
+ at node Interfacing with Erlang
+ at subsection Interfacing with Erlang
+
+ at menu
+* Using pragma foreign_type for Erlang :: Declaring Erlang types in Mercury
+* Using pragma foreign_proc for Erlang :: Calling Erlang code from Mercury
+* Using pragma foreign_export for Erlang :: Calling Mercury from Erlang code
+* Using pragma foreign_decl for Erlang :: Including Erlang declarations in Mercury
+* Using pragma foreign_code for Erlang :: Including Erlang code in Mercury
+ at end menu
+
+
+ at node Using pragma foreign_type for Erlang
+ at subsubsection Using pragma foreign_type for Erlang
+
+An Erlang @samp{pragma foreign_type} declaration has the form:
+
+ at example
+:- pragma foreign_type("Erlang", @var{MercuryTypeName}, "").
+ at end example
+
+The effect of this declaration is that Mercury values of type
+ at var{MercuryTypeName} will be passed to and from Erlang foreign_procs
+as having some representation unknown to Mercury.
+
+ at node Using pragma foreign_proc for Erlang
+ at subsubsection Using pragma foreign_proc for Erlang
+
+The input and output variables for a Erlang @samp{pragma foreign_proc}
+will be the Erlang representations as described in
+ at ref{Erlang data passing conventions}.
+
+The Erlang code in a @code{pragma foreign_proc} declaration
+for a procedure whose determinism indicates that it can fail
+must assign either @samp{true} or @samp{false} to the variable
+ at samp{SUCCESS_INDICATOR}. For example:
+
+ at example
+:- pred string.contains_char(string, character).
+:- mode string.contains_char(in, in) is semidet.
+
+:- pragma foreign_proc("Erlang",
+ string.contains_char(Str::in, Ch::in),
+ [will_not_call_mercury, promise_pure],
+ "SUCCESS_INDICATOR = (string:chr(Str, Ch) =/= 0)").
+ at end example
+
+Arguments whose mode is input will have their values set by the
+Mercury implementation on entry to the Erlang code.
+The Erlang code must set the values
+of all output variables, even if the procedure fails
+(i.e. sets the @samp{SUCCESS_INDICATOR} variable to @code{false}).
+
+ at node Using pragma foreign_export for Erlang
+ at subsubsection Using pragma foreign_export for Erlang
+
+A @samp{pragma foreign_export} declaration for Erlang has the form:
+
+ at example
+:- pragma foreign_export("Erlang", @var{MercuryMode}, "@var{Erlang_Name}").
+ at end example
+
+For example,
+
+ at example
+:- pragma foreign_export("Erlang", foo(in, in, out), "foo").
+ at end example
+
+ at c XXX currently foreign_exported procedures won't be visible outside
+ at c the defining module.
+
+The type signature of the Erlang interface to a Mercury procedure is
+described in @ref{Erlang data passing conventions}.
+
+Calling polymorphically typed Mercury procedures from Erlang is a little bit
+more difficult than calling ordinary (monomorphically typed) Mercury
+procedures. The simplest method is to just create monomorphic forwarding
+procedures that call the polymorphic procedures, and export them, rather
+than exporting the polymorphic procedures.
+
+If you do export a polymorphically typed Mercury procedure, the compiler
+will prepend one @samp{type_info} argument to the parameter list of
+the Erlang interface function for each polymorphic type variable in the
+Mercury procedure's type signature. The caller must arrange to pass
+in appropriate @samp{type_info} values corresponding to the types
+of the other arguments passed. These @samp{type_info} arguments can
+be obtained using the Mercury @samp{type_of} function in the Mercury
+standard library module @samp{type_desc}.
+
+ at node Using pragma foreign_decl for Erlang
+ at subsubsection Using pragma foreign_decl for Erlang
+
+ at samp{pragma foreign_decl} declarations for Erlang can be used to provide
+any top-level Erlang declarations (e.g.@: @samp{-define} macro declarations)
+which are needed by Erlang code.
+
+ at samp{pragma foreign_decl} blocks which do not have the @samp{local} attribute
+will be copied into the @samp{.hrl} header file for that module, and
+automatically included by other modules that import the module. Therefore
+ at samp{-export} directives and Erlang module attributes should only appear in
+ at samp{local} blocks.
+
+For example:
+
+ at example
+:- pragma foreign_decl("Erlang", "
+ -define(FOO, 42).
+").
+:- pred hello(io.state::di, io.state::uo) is det.
+:- pragma foreign_proc("Erlang",
+ hello(_IO0::di, _IO::uo),
+ [will_not_call_mercury],
+"
+ io:format(""FOO = ~w~n"", [?FOO])
+").
+ at end example
+
+ at node Using pragma foreign_code for Erlang
+ at subsubsection Using pragma foreign_code for Erlang
+
+ at samp{pragma foreign_code} can be used to define additional Erlang functions
+which can then be referenced by @samp{pragma foreign_proc} declarations for
+Erlang from that module. By adding @samp{-export} directives inside
+ at samp{pragma foreign_decl} declarations, those functions can additionally be
+called from outside the defining module.
+
+For example:
+
+ at example
+:- pragma foreign_code("Erlang", "
+ foo() -> io:put_chars(""Foo."").
+").
+
+:- impure pred say_foo is det.
+:- pragma foreign_proc("Erlang", say_foo,
+ [will_not_call_mercury], "foo()").
+ at end example
+
+ at c ----------------------------------------------------------------------------
+
@node C interface
@chapter C interface
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.535
diff -u -r1.535 user_guide.texi
--- doc/user_guide.texi 14 Jul 2007 02:33:00 -0000 1.535
+++ doc/user_guide.texi 18 Jul 2007 02:37:34 -0000
@@ -689,6 +689,11 @@
@vindex EXTRA_JAVACFLAGS
Options to pass to the Java compiler (if you are using it).
+ at item ERLANG_FLAGS and EXTRA_ERLANG_FLAGS
+ at vindex ERLANG_FLAGS
+ at vindex EXTRA_ERLANG_FLAGS
+Options to pass to the Erlang compiler (if you are using it).
+
@item ML
@vindex ML
The executable that invokes the linker.
@@ -7443,7 +7448,7 @@
generated code, and also output some profiling
information (the static call graph) to the file
@samp{@var{module}.prof}. @xref{Profiling}.
-This option is not supported for the IL and Java back-ends.
+This option is not supported for the IL, Java and Erlang back-ends.
@sp 1
@item @code{--memory-profiling} (grades: any grade containing @samp{.memprof})
@@ -7456,14 +7461,15 @@
generated code, and also output some profiling
information (the static call graph) to the file
@samp{@var{module}.prof}. @xref{Using mprof for memory profiling}.
-This option is not supported for the IL and Java back-ends.
+This option is not supported for the IL, Java and Erlang back-ends.
@sp 1
@item @code{--deep-profiling} (grades: any grade containing @samp{.profdeep})
@findex --deep-profiling
@cindex Deep profiling
Enable deep profiling by inserting the appropriate hooks in the generated code.
-This option is not supported for the high-level C, IL and Java back-ends.
+This option is not supported for the high-level C, IL, Java and Erlang
+back-ends.
@ignore
The following are basically useless, hence undocumented.
@@ -7535,8 +7541,8 @@
@samp{mps} is another conservative collector based on Ravenbrook Limited's
MPS (Memory Pool System) kit.
@samp{automatic} means the target language provides it.
-This is the case for the IL and Java back-ends, which always use
-the underlying IL or Java implementation's garbage collector.
+This is the case for the IL, Java and Erlang back-ends, which always use
+the underlying implementation's garbage collector.
@sp 1
@item @code{--use-trail} (grades: any grade containing @samp{.tr})
@@ -7548,7 +7554,7 @@
Enable use of a trail.
This is necessary for interfacing with constraint solvers,
or for backtrackable destructive update.
-This option is not yet supported for the IL or Java back-ends.
+This option is not yet supported for the IL, Java or Erlang back-ends.
@sp 1
@item @code{--maybe-thread-safe @{yes, no@}}
@@ -7568,6 +7574,7 @@
floating point values don't need to be boxed. Double
precision floats are used by default.
This option is not yet supported for the IL or Java back-ends.
+This option will not be supported for the Erlang back-end.
@c RBMM is undocumented since it is still experimental.
@c @sp 1
Index: library/Mercury.options
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/library/Mercury.options,v
retrieving revision 1.26
diff -u -r1.26 Mercury.options
--- library/Mercury.options 2 Jul 2007 05:30:32 -0000 1.26
+++ library/Mercury.options 18 Jul 2007 02:37:34 -0000
@@ -71,6 +71,5 @@
MCFLAGS-thread += --no-local-thread-engine-base
MCFLAGS-thread.semaphore += --no-local-thread-engine-base
-# Ignore warnings about missing clauses for builtin_compare_eq,
-# builtin_compare_lt until the compiler knows these are builtins.
-MCFLAGS-private_builtin += --allow-stubs --no-halt-at-warn
+# Work around a problem in the HiPE compiler (as of Erlang R11B5).
+MCFLAGS-bitmap += --no-erlang-native-code
Index: library/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/library/Mmakefile,v
retrieving revision 1.149
diff -u -r1.149 Mmakefile
--- library/Mmakefile 14 Jul 2007 02:33:08 -0000 1.149
+++ library/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -97,11 +97,11 @@
MCFLAGS += --flags LIB_FLAGS $(CONFIG_OVERRIDE)
MCFLAGS += $(LIBRARY_TRACE_LEVEL) $(INTER_FLAGS)
-# The IL and Java implementations of the standard library are not yet complete,
-# so we need to pass `--allow-stubs' to get them to compile.
+# The IL, Java and Erlang implementations of the standard library are not yet
+# complete, so we need to pass `--allow-stubs' to get them to compile.
# Since the standard library is compiled with `--halt-at-warn',
# we also need `--no-warn-stubs'.
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
MCFLAGS += --allow-stubs --no-warn-stubs
endif
@@ -358,7 +358,7 @@
#
# Some extra rules that we need for the C and asm back-ends
#
-ifeq ("$(findstring il,$(GRADE))$(findstring java,$(GRADE))","")
+ifeq ("$(filter il% java% erlang%,$(GRADE))","")
# The following dependency is just there to improve compilation speed;
# making tree234.$O first improves effective parallelism with parallel makes.
@@ -379,7 +379,7 @@
endif
-endif # GRADE != il && GRADE != java
+endif # GRADE != il && GRADE != java && GRADE != erlang
#-----------------------------------------------------------------------------#
Index: mdbcomp/MDBCOMP_FLAGS.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/mdbcomp/MDBCOMP_FLAGS.in,v
retrieving revision 1.1
diff -u -r1.1 MDBCOMP_FLAGS.in
--- mdbcomp/MDBCOMP_FLAGS.in 6 May 2005 08:42:17 -0000 1.1
+++ mdbcomp/MDBCOMP_FLAGS.in 18 Jul 2007 02:37:34 -0000
@@ -10,6 +10,7 @@
--c-include-directory ../runtime
--c-include-directory ../library
--c-include-directory ../library/Mercury/mihs
+--erlang-include-directory ../library/Mercury/hrls
-L../boehm_gc
-L../runtime
-L../library
Index: mdbcomp/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/mdbcomp/Mmakefile,v
retrieving revision 1.11
diff -u -r1.11 Mmakefile
--- mdbcomp/Mmakefile 8 Jan 2007 07:07:04 -0000 1.11
+++ mdbcomp/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -85,11 +85,11 @@
#-----------------------------------------------------------------------------#
-# The IL and Java implementations of the standard library are not yet complete,
-# so we need to pass `--allow-stubs' to get them to compile.
+# The IL, Java and Erlang implementations of the standard library are not yet
+# complete, so we need to pass `--allow-stubs' to get them to compile.
# Since the standard library is compiled with `--halt-at-warn',
# we also need `--no-warn-stubs'.
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
MCFLAGS += --allow-stubs --no-warn-stubs
endif
@@ -240,9 +240,9 @@
mkdir -p $(INSTALL_GRADE_MODULE_DIR)
[ -d $(INSTALL_MERC_LIB_DIR) ] || mkdir -p $(INSTALL_MERC_LIB_DIR)
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
-# there is no debugger in the .NET and Java backends
+# there is no debugger in the .NET, Java, Erlang backends
.PHONY: install_init
install_init:
Index: profiler/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/profiler/Mmakefile,v
retrieving revision 1.27
diff -u -r1.27 Mmakefile
--- profiler/Mmakefile 6 May 2005 08:42:19 -0000 1.27
+++ profiler/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -37,7 +37,7 @@
# Add some additional dependencies, so that Mmake knows to remake the
# profiler if one of the libraries changes.
-ifeq ("$(filter il% java%,$(GRADE))","")
+ifeq ("$(filter il% java% erlang%,$(GRADE))","")
mercury_profile: $(RUNTIME_DIR)/lib$(RT_LIB_NAME).$A
mercury_profile: $(LIBRARY_DIR)/lib$(STD_LIB_NAME).$A
# XXX Should also depend on $(BOEHM_GC_DIR)/libgc(_prof).$A, but only
Index: runtime/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/runtime/Mmakefile,v
retrieving revision 1.139
diff -u -r1.139 Mmakefile
--- runtime/Mmakefile 14 Jul 2007 02:33:19 -0000 1.139
+++ runtime/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -329,13 +329,13 @@
.PHONY: all
all: runtime $(TAGS_FILE_EXISTS)
-ifeq ($(findstring java,$(GRADE)),java)
+ifneq "$(filter java% erlang%,$(GRADE))" ""
#
-# For grade java, there's nothing to do
+# For grade java and erlang, there's nothing to do
.PHONY: runtime
runtime:
- @echo "No Mercury runtime needed for grade=java"
+ @echo "No Mercury runtime needed for grade=java and grade=erlang"
else
ifeq ($(findstring il,$(GRADE)),il)
@@ -445,12 +445,13 @@
-[ -d $(INSTALL_RECONF_DIR)/runtime ] || \
mkdir -p $(INSTALL_RECONF_DIR)/runtime
-ifeq ($(findstring java,$(GRADE)),java)
+ifneq "$(filter java% erlang%,$(GRADE))" ""
-# For grade java, there's nothing to do.
+# For grade java and erlang, there's nothing to do.
# (The java version of the Mercury runtime is in mercury/java/runtime,
# not mercury/runtime, and its build and installation is handled by
# mercury/library/Mmakefile.)
+# (Runtime support for the Erlang backend is in the library directory.)
.PHONY: install_headers
install_headers:
Index: scripts/Mercury.config.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/Mercury.config.in,v
retrieving revision 1.17
diff -u -r1.17 Mercury.config.in
--- scripts/Mercury.config.in 15 Nov 2006 08:12:56 -0000 1.17
+++ scripts/Mercury.config.in 18 Jul 2007 02:37:34 -0000
@@ -27,6 +27,8 @@
MERCURY_JAVA_COMPILER=@JAVAC@
MERCURY_JAVA_INTERPRETER=@JAVA_INTERPRETER@
MERCURY_CSHARP_COMPILER=@MS_CSC@
+MERCURY_ERLANG_COMPILER=@ERLC@
+MERCURY_ERLANG_INTERPRETER=@ERL@
# $(MATH_LIB) needs to be defined because it may
# be used by the substitution for SHARED_LIBS.
MATH_LIB=$(MERCURY_MATH_LIB)
@@ -52,6 +54,8 @@
--java-compiler "$(MERCURY_JAVA_COMPILER)" \
--java-interpreter "$(MERCURY_JAVA_INTERPRETER)" \
--csharp-compiler "$(MERCURY_CSHARP_COMPILER)" \
+ --erlang-compiler "$(MERCURY_ERLANG_COMPILER)" \
+ --erlang-interpreter "$(MERCURY_ERLANG_INTERPRETER)" \
--cflags-for-ansi "@CFLAGS_FOR_ANSI@" \
--cflags-for-optimization "@CFLAGS_FOR_OPT@" \
--cflags-for-warnings "@CFLAGS_FOR_WARNINGS@" \
Index: scripts/final_grade_options.sh-subr
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/final_grade_options.sh-subr,v
retrieving revision 1.15
diff -u -r1.15 final_grade_options.sh-subr
--- scripts/final_grade_options.sh-subr 1 Nov 2006 02:31:17 -0000 1.15
+++ scripts/final_grade_options.sh-subr 18 Jul 2007 02:37:34 -0000
@@ -79,9 +79,9 @@
esac
#
-# --target IL or Java implies --gc automatic
+# --target IL or Java or Erlang implies --gc automatic
#
-case $target in il|java)
+case $target in il|java|erlang)
gc_method=automatic ;;
esac
Index: scripts/parse_grade_options.sh-subr
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/parse_grade_options.sh-subr,v
retrieving revision 1.35
diff -u -r1.35 parse_grade_options.sh-subr
--- scripts/parse_grade_options.sh-subr 12 Jun 2007 06:39:20 -0000 1.35
+++ scripts/parse_grade_options.sh-subr 18 Jul 2007 02:37:34 -0000
@@ -32,6 +32,8 @@
target=il ;;
java|Java)
target=java ;;
+ erlang|Erlang)
+ target=erlang ;;
*)
echo "$0: invalid target \`$1'" 1>&2
exit 1
@@ -45,6 +47,9 @@
--java|--Java|--java-only|--Java-only)
target=java ;;
+ --erlang|--Erlang|--erlang-only|--Erlang-only)
+ target=erlang ;;
+
--high-level-code|-H)
highlevel_code=true ;;
--no-high-level-code|-H-)
@@ -275,6 +280,9 @@
gcc_nested_functions=false
highlevel_data=true
;;
+ erlang)
+ target=erlang
+ ;;
hl)
asm_labels=false
non_local_gotos=false
Index: slice/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/slice/Mmakefile,v
retrieving revision 1.11
diff -u -r1.11 Mmakefile
--- slice/Mmakefile 12 Jun 2007 14:41:46 -0000 1.11
+++ slice/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -89,7 +89,7 @@
# Add some additional dependencies, so that Mmake knows to remake the
# slicer and dicer if one of the libraries changes.
-ifeq ("$(filter il% java%,$(GRADE))","")
+ifeq ("$(filter il% java% erlang%,$(GRADE))","")
mslice: $(RUNTIME_DIR)/lib$(RT_LIB_NAME).$A
mslice: $(LIBRARY_DIR)/lib$(STD_LIB_NAME).$A
mslice: $(BROWSER_DIR)/lib$(BROWSER_LIB_NAME).$A
Index: trace/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/trace/Mmakefile,v
retrieving revision 1.53
diff -u -r1.53 Mmakefile
--- trace/Mmakefile 15 Jun 2007 08:26:46 -0000 1.53
+++ trace/Mmakefile 18 Jul 2007 02:37:34 -0000
@@ -218,8 +218,8 @@
.PHONY: all
.PHONY: trace
-ifneq ("$(filter il% java%,$(GRADE))","")
-# there is no tracing in the .NET and Java backends
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
+# there is no tracing in the .NET, Java, Erlang backends
all:
@@ -317,9 +317,9 @@
.PHONY: install
install: install_headers install_lib
-ifneq ("$(filter il% java%,$(GRADE))","")
+ifneq ("$(filter il% java% erlang%,$(GRADE))","")
-# there is no tracing in the .NET and Java backends
+# there is no tracing in the .NET, Java, Erlang backends
.PHONY: install_headers
install_headers:
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to: mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions: mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------
More information about the reviews
mailing list