Parrot Virtual Machine/Building Parrot

Obtaining Parrot

edit

The most recent development release of Parrot can be downloaded from CPAN.

Development of Parrot is controlled through the SVN repository at http://svn.parrot.org/parrot/. The most up-to-date version of Parrot can be obtained from https://svn.parrot.org/parrot/trunk/ via svn checkout.

Building Parrot From Source

edit

Parrot is currently available as a source code download, although some people are trying to maintain precompiled versions for download as well. These versions are typically available for Windows, Cygwin, Debian, and Red Hat. Other binary distributions may be added in the future. Instructions for installing a precompiled binary distribution of Parrot for your system vary depending on the particular platform and the method in which it was bundled. Consult the accompanying documentation for any distribution you download for more details. This page will not discuss these particular distributions, only the method of building Parrot from the original source code.

On a Windows platform, substitute the freely-available nmake instead of make.

Currently the Parrot build process requires the use of make, a working C compiler, and a working Perl 5 installation. Perl should be version 5.8 or higher. Without these things, it will not be possible for you to build Parrot. Automated testing is performed on a variety of systems with various combinations of these tools, and any particular revision should be able to be compiled properly. If you have problems compiling Parrot on your system, send an email to the Parrot Porters mailing list with details of the problems, and one of the Parrot developers will try to help fix it.

Configure.pl

edit
Notice that Configure.pl has a capitalized first letter. This is an important distinction on Unix and Linux systems which are case sensitive.

The first step in building Parrot is to run the Configure.pl script which will perform some basic tests on your system and produce a makefile. To automatically invoke Configure.pl with the most common options, run the program Makefile.pl instead. The configuration process performs a number of tests on your system to determine some important parameters. These tests may make several minutes on some systems, so be patient. In addition, configuration creates a number of platform-specific code files for your system. Without these generated files in place, the build process cannot procede.

After Configure.pl is finished executing, you should have a file named Makefile (with no suffix). From the shell, go to the Parrot directory and type the command "make" or "nmake" on Windows. This will start the process to build Parrot. The Parrot build process could take several minutes because there are a number of steps. We will discuss some of these steps in a later section.

MANIFEST

edit

The root directory of Parrot contains a file called MANIFEST. MANIFEST contains a list of all necessary files in the Parrot repository. If you add a new file to the Parrot source tree, make sure to add that file to MANIFEST. Configure.pl checks MANIFEST to ensure all files exist properly before attempting to build.

Configure.pl Options

edit

Depending on what tasks you want to perform, or how you are using Parrot, there are a number of options that can be specified to Configure.pl. These options may change the makeup of several generated files, including the Makefile. Here, we will list some of these options:

--help Shows a help message
--version Prints version information about Configure.pl
--verbose Prints extra information to the console
--fatal If any step fails, kill Configure immediately and do not run additional tests
--silent No output to the console
--nomanicheck Do not check the file MANIFEST to ensure all files exist.
--languages Specify a comma-separated list of languages to build also, after Parrot has been built.
--ask Ask the user for answers to common questions, instead of running probes.
--test Test the configuration tools first, then Configure, then the build tools. Use --test=configure to test the configuration tools then run Configure.pl. Use--test=build to run Configure.pl and then also test the build tools.
--debugging set --debugging=0 to turn off debugging. Debugging is on by default.
--inline Specify whether your C compiler supports inline code using the C inline keyword.
--optimize Compile Parrot using compiler optimizations, and a few other speed-up tricks. Creates a faster bird, but may expose more errors and failures. Use --optimize=(flags) to specify compiler optimization flags to use.
--parrot_is_shared Link Parrot dynamically to libparrot, instead of linking statically.
--m=32 On a 64-bit platform, compile a 32-bit Parrot.
--profile Turn on profiling. Only used with the GCC compiler, for now.
--cage Turn on additional warnings, for the Cage Cleaners.
--cc Specify the compiler to use. For instance, --cc=gcc for the GCC compiler, and --cc=cl for Microsoft's C++ compiler. Use --ccflags to specify any additional compiler flags, and --ccwarn to turn on any additional warnings. Here are some more options:
  1. To build Parrot with a C++ compiler, use --cxx to specify the compiler to use.
  2. Use --libs to specify any additional libraries to link Parrot with.
  3. Use --link to specify a linker
  4. Use --linkflags to send options to the linker
  5. Use --ld to select a loader
  6. Use --ldflags to send flags to the loader
  7. Use --make to specify what make utility to use
--intval --floatval --opcode Set the C data types to use for each value. Notice that --intval and --opcode must be the same, or strange errors may result.
--ops Specify any optional OPS files to build.
--pmc Specify any optional PMC files to build.
--without-gmp Do not use
--without gdbm Build Parrot without GMP
--without-opengl Build Parrot without OpenGL support
--without-crypto Build Parrot witout the cryptography library
--icu-config Specify a location for the Unicode ICU library on your system.
--without-icu Build Parrot without ICU and Unicode support.
--maintainer Compile IMCC's tokenizer and parser using Lex and Yacc (or equivalent). Use --lex to specify the name of the lexer, nd --yacc to specify the name of the parser.
--miniparrot Build miniparrot
--prefix Specify a path prefix
--exec-prefix Specify an execution path prefix
--bindir The directory for binary executable files on your system
--sbindir The system admin executables folder
--libexecdir Program executables folder
--datadir read-only data directory for machine-independent data.
--sysconfdir read-only data that is machine dependent
--sharedstatedir modifiable architecture-independent data directory
--localstatedir modifiable architecture-dependet data directory
--libdir Object code directory
--includedir Folder for Compiler include files
--oldincludedir C header file directory for old versions of GCC
--infodir info documentation directory
--mandir Man pages docmentation folder

Parrot Executable

edit

After the build process you should have, among other things, an executable file for Parrot. This will be, on Windows systems, named parrot.exe. On other systems, it may be named slightly differently, such as with no suffix.

Two other programs of interest are created, miniparrot.exe and libparrot.dll. These files will be named something different if you are not on a Windows system.

Make Targets

edit

For readers who are not familiar with the make program, it is a program which can be used to automatically determine how to build a software project from source code files. In a makefile, you specify a list of dependencies, and the method for producing one file from others. make then determines the order and method to build your project.

make has targets, which means a single makefile can have multiple goals. For Parrot, a number of targets have been defined which can help with building, debugging, and testing. Here are a list of some of the make targets:

Command Explanation
make Builds Parrot from source. Only rebuilds components that have changed from the last build.
make clean removes all the intermediate files that are left over from the build process. Cleans the directory tree so that Parrot can be completely rebuilt.
make realclean Completely removes all temporary files, all intermediate files, and all makefiles. After a make realclean command, you will need to run Configure.pl again.
make test Builds Parrot, if needed, and runs the test suite on it. If there are errors in the test results, you can try to fix them yourself, or you can submit a bug report to the Parrot developers. This is always appreciated.
make fulltest Build Parrot, if needed, and runs the test suit on every run core. This can be a very time-consuming operation, and is typically only performed prior to a new release.
make smoke Performs smoke testing. This runs the parrot test suite and attempts to transmit the test results directly to the Parrot development servers. Smoke test results help the developers to keep track of the systems where Parrot is building correctly.

Submitting Bugs and Patches

edit

As we mentioned above, smoke testing is an easy way for you to help submit information about Parrot on your system. Since Parrot is supposed to support so many different computer architectures and operating systems, it can be difficult to know how Parrot is performing on all of them.

Besides smoke testing, there are a number of ways that you can submit a bug report to Parrot. If you are a capable programmer, you may be interested in trying to make fixes and submit patches as well.

Resources

edit


Previous Parrot Virtual Machine Next
Introduction Running_Parrot