mirror of
https://github.com/Mercury-Language/mercury.git
synced 2025-12-08 18:34:00 +00:00
07a0d9977f
README.CSharp:
README.Erlang:
README.Java:
Users should use the --grade option to build programs using these
backends. Delete the wording that suggests using compilation model
options like --java or --csharp to do that. Without specifying
additional compilation model options that will not work.
261 lines
8.5 KiB
Plaintext
261 lines
8.5 KiB
Plaintext
-----------------------------------------------------------------------------
|
|
|
|
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.
|
|
|
|
WARNING
|
|
|
|
The Erlang backend is incomplete, and will not see any more work in
|
|
the future. It has not been tested for version 20.01 of the Mercury system.
|
|
|
|
Large parts of the Mercury standard library are not yet implemented.
|
|
Some RTTI related features are incompletely or incorrectly implemented.
|
|
Binary stream I/O and Unicode support are known to be broken after
|
|
changes in Erlang/OTP since the original port.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
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>
|
|
|
|
- A Unix-like environment. The Erlang support has not been
|
|
tested on Windows, but you will need a shell script
|
|
interpreter.
|
|
|
|
- Users of Debian or Ubuntu who are using the Erlang that is
|
|
packaged for those systems also need have the erlang-dev
|
|
package installed.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
INSTALLATION
|
|
|
|
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 install
|
|
or
|
|
mmake 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 the option `--grade 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 install the
|
|
Mercury library in the erlang grade, as described above.
|
|
|
|
You can now build programs such as hello.m or calculator.m in the samples
|
|
directory.
|
|
|
|
cd samples
|
|
mmc --grade erlang --make hello
|
|
|
|
Note that when building programs using the erlang grade you *must* use
|
|
mmc --make.
|
|
|
|
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'.
|
|
|
|
If you are using the Windows command-line interpreter, i.e. cmd.exe, then
|
|
setting the value of option --target-env-type to "windows" will cause the
|
|
compiler to generate a batch file that starts the Erlang runtime system, rather
|
|
than a shell script.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
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.mercurylang.org/information/documentation.html>
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
BUILDING THE MERCURY COMPILER IN THE ERLANG GRADE
|
|
|
|
Building the Mercury compiler and other related tools in the Erlang grade
|
|
is NOT generally supported and should be considered experimental.
|
|
In particular, a Mercury compiler built in the Erlang grade may be slower than
|
|
normal and some features may not be available.
|
|
|
|
However, if you want to give it a try, the required steps are:
|
|
|
|
(1) Ensure that you have an existing working Mercury compiler in your PATH
|
|
and a clean version of the Mercury source tree.
|
|
|
|
(2) Run ./prepare.sh; ./configure as normal.
|
|
|
|
(3) Add the line:
|
|
|
|
GRADE=erlang
|
|
|
|
to a file named Mmake.params at the top-level of the source tree.
|
|
|
|
(4) Begin the build process using the following command:
|
|
|
|
$ mmake --use-mmc-make GRADE=erlang
|
|
|
|
The Erlang version of the compiler MUST be built using mmake's --use-mmc-make
|
|
option; the build will not work otherwise. Setting the variable GRADE in the
|
|
invocation of mmake is currently necessary in order to avoid some variable
|
|
definition ordering problems in Mmake.workspace.
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
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 this problem does not occur.
|
|
|
|
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 it makes a conservative assumption. Enabling intermodule optimisation
|
|
gives the compiler more information to avoid this problem.
|
|
|
|
For some programs you may want to increase the default heap size.
|
|
You can do this by setting the ERL_FLAGS environment variable, e.g.
|
|
export ERL_FLAGS="+h8000".
|
|
|
|
-----------------------------------------------------------------------------
|
|
|
|
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.mercurylang.org/backends.html>
|
|
|
|
<http://www.mercurylang.org/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. Erlang/OTP R14B04 or later is required.
|
|
|
|
|
|
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
|
|
tabling
|
|
|
|
The following implementation features are not supported:
|
|
|
|
Mercury-level debugging
|
|
Mercury-level profiling
|
|
backjumping
|
|
|
|
The following standard library modules are completely unimplemented:
|
|
|
|
bit_buffer
|
|
thread
|
|
thread.semaphore
|
|
time
|
|
version_array
|
|
|
|
In addition, many modules are incompletely implemented or have placeholder
|
|
implementations.
|
|
|
|
Q. 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.
|
|
|
|
-----------------------------------------------------------------------------
|