Parrot Virtual Machine/Building Parrot

Obtaining Parrot

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

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

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

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

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: To build Parrot with a C++ compiler, use --cxx to specify the compiler to use. Use --libs to specify any additional libraries to link Parrot with. Use --link to specify a linker Use --linkflags to send options to the linker Use --ld to select a loader Use --ldflags to send flags to the loader 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

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

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

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

• http://www.parrotcode.org/docs/gettingstarted.html