=pod

=head1 NQP - Not Quite Perl

NQP is Copyright (C) 2009-2019 by The Perl Foundation.  See F<LICENSE>
for licensing details.

This is "Not Quite Perl" -- a lightweight Raku-like environment for
virtual machines.  The key feature of NQP is that it's designed to be a very
small environment (as compared with, say, raku or Rakudo) and is focused on
being a high-level way to create compilers and libraries for virtual
machines like MoarVM [1], the JVM, and others.

Unlike a full-fledged implementation of Raku, NQP strives to have as small
a runtime footprint as it can, while still providing a Raku object model
and regular expression engine for the virtual machine.

    [1] https://github.com/MoarVM/MoarVM

=head2 Building from source

=for HTML <a href="https://dev.azure.com/Raku/nqp/_build/latest?definitionId=1&branchName=master"><img src="https://dev.azure.com/Raku/nqp/_apis/build/status/Raku.nqp?branchName=master"></a>

=for HTML <a href="https://travis-ci.org/raku/nqp"><img src="https://travis-ci.org/raku/nqp.svg?branch=master"></a>

To build NQP from source, you'll just need a C<make> utility and C<Perl> 5.8 or
newer.  To automatically obtain and build MoarVM you may also need
a C<git> client.

To obtain C<NQP> directly from its repository:

    $ git clone git://github.com/Raku/nqp.git

If you don't have git installed, you can get a tarball or zip of NQP from
github by visiting http://github.com/Raku/nqp/tree/master and clicking
"Download".  Then unpack the tarball or zip.

C<NQP> can run on three different backends: C<MoarVM>, the C<JVM>, and C<JavaScript>.
The C<JVM> and C<JavaScript> backends are currently experimental.  The JVM backend
requires C<JDK 1.9> (also known as C<JDK 9>) or higher.

Decide on which backends you want it to run, and configure and build it as
follows:

Once you have a copy of NQP, build it as follows:

    $ cd nqp
    $ perl Configure.pl --backends=moar,jvm
    $ make

If you don't have an installed MoarVM, you can have
C<Configure.pl> build one for you by passing the C<--gen-moar> option to it as well.

The C<make> step will create a C<nqp> or C<nqp.exe> executable in the current
directory.  Programs can then be run from the build directory using a
command like:

    $ ./nqp hello.nqp

By default, NQP searches for the MoarVM executable and installs to the
directory C<./install>. You can change that with the C<--prefix> option to
Configure.pl.

Once built, NQP's C<make install> target will install NQP and its libraries
into the same location as the MoarVM installation
that was used to create it.  Until this step is
performed, the C<nqp> executable created by C<make> above can only be
reliably run from the root of NQP's build directory.  After C<make install>
is performed the executable can be run from any directory.

If the C<NQP> compiler is invoked without an explicit script to run, it enters
a small interactive mode that allows statements to be executed from the
command line.  Each line entered is treated as a separate compilation unit,
however (which means that subroutines are preserved after they are defined,
but variables are not).

=head2 Troubleshooting

=head3 OS X

On OS X, it appears that configuration fails in some configurations:

  3rdparty/libuv/include/uv-darwin.h:26:11: fatal error: 'mach/mach.h' file not found

Should this happen to you, then a solution might be the following:

    $ cd MoarVM/3rdparty/libuv/include
    $ ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/usr/include/mach
    $ cd ../../../..
    $ # run the Configure again

Note that the 10.9 in the above, represents the major version of OS X being
used.  On Mavericks use 10.9 (like above), on Yosemite use 10.10.

=head2 Using NQP

B<NOTE:> there's B<no end-user support> for NQP and the behaviour can
change without notice. It's a tool for writing Raku compilers, not a
low-level module for Raku programmers.

The L<examples directory|https://github.com/perl6/nqp/tree/master/examples> is a good place to start, with the
L<loops|https://github.com/perl6/nqp/blob/master/examples/loops.nqp> and other files. Opcodes are listed in
L<the docs directory|https://github.com/perl6/nqp/blob/master/docs/ops.markdown>. NQP also has built-in routines
listed in L<the docs directory|https://github.com/perl6/nqp/blob/master/docs/built-ins.md>. You can use NQP from this
release, it will be already installed if you have built Raku from
scratch.

=head2 JavaScript backend

The best thing before playing with it/hacking on it is to contact pmurias via IRC at C<#raku> on L<irc.freenode.org|https://webchat.freenode.net/?channels=#raku>.
We depend on C<node.js> at least 10.10.0

Building the JavaScript backend currently requires building the moar backend:

    $ perl Configure.pl --backends=moar,js
    $ make

Currently it needs to be run like:

    $ ./nqp-js file.nqp

If you are developing C<nqp-js>, you may want to pass the C<--link> option to configure to have the C<nqp-runtime> linked instead of installed

    $ cd src/vm/js/nqp-runtime; npm link .
    $ perl Configure --backends=moar,js

=cut
