Parrot Virtual Machine/Building 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
|This page may be out of date, since Parrot is still in active development. The most up-to-date treatment of the Parrot build procedure is discussed at http://www.parrotcode.org/source.html|
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.
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.plhas 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.
|Parrot uses local defaults for several values, depending on the settings of your system. Therefore, Parrot may use different values for things like the size of an INTVAL from what it is on another computer. This behavior, of using local defaults, means that programs compiled into bytecode by your version of Parrot (or a version built by somebody else on the same platform) will run faster than those written on another platform. We will talk more about this translation process in a later chapter.|
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.
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.
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
|--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:
|--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.|
|--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|
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.
|This book will simply use "parrot" as the command to invoke Parrot. This may be different on your system.|
Two other programs of interest are created,
libparrot.dll. These files will be named something different if you are not on a Windows system.
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:
||Builds Parrot from source. Only rebuilds components that have changed from the last build.|
||removes all the intermediate files that are left over from the build process. Cleans the directory tree so that Parrot can be completely rebuilt.|
||Completely removes all temporary files, all intermediate files, and all makefiles. After a
||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.|
||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.|
||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.