# 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.
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

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