Tamarin source versions
The following instructions are for obtaining and building the Tamarin Central source code. For instructions on Tamarin Tracing, please see Tamarin Tracing Build Documentation.
Supported platforms
Tamarin currently supports the following operating systems and/or architectures.
- Windows 32 and 64 bit
- Mac OSX 10.4, 10.5 on PPC
- Mac OSX 10.5, 10.6 on Intel
- Linux 32 and 64 bit
- Solaris 10 on SPARC
- Android 2.2 on ARM
- Windows Mobile 6.5
- MIPS (Linux)
- SH4 (Linux)
Getting the Tamarin source
The Tamarin source resides in Mercurial at Tamarin Central. Active development source resides at Tamarin Redux. In this document replace instances of tamarin-central with tamarin-redux to operate in the redux repository. Use the following command to create a copy of the Tamarin repository:
$ hg clone http://hg.mozilla.org/tamarin-central tamarin-central
Tips for working with Mercurial can be found here.
Building Tamarin
Building Tamarin will create all the libraries for the AVMPlus and garbage collector (MMgc), and create a standalone executable (shell) for executing files in the ABC file format. Running the shell without any arguments will list the available options. Note that additional command-line arguments are only available in the debug configuration.
The Tamarin codebase contains a cross-platform build system for Mozilla developers. The cross-platform build system is used for daily automated build testing so it is the most reliable system.
The Tamarin codebase has the ability to build additional code which supports debugging hooks. In the XCode project, this is the Debug_Debugger and Release_Debugger configurations. The Flash Player builds Tamarin with the debugging hooks off for codesize reasons, but the Mozilla client will build Tamarin with the debugging hooks on.
Cross-platform build (general instructions - non-android)
Prerequisites: You need Python 2.5 or later and GNU make 3.81 or later. (GNU make 3.80 does not work. Nor does any other brand of make.)
With the right prerequisites, use these commands to build Tamarin:
$ hg clone http://hg.mozilla.org/tamarin-redux/ $ cd tamarin-redux $ mkdir objdir-release $ cd objdir-release $ python ../configure.py $ make ... $ shell/avmshell shell 1.0 build cyclone ...
The AVMPlus executable is avmshell.
Optional Flags:
--enable-debugger- Debugger build--enable-debug- Debug build
For verbose build of Tamarin, you can pass CPPFLAGS to make.
$ make CPPFLAGS=-DAVMPLUS_VERBOSE
Additional instructions for non-android cross-platform Tamarin-redux build on OSX 10.6 (Snow Leopard)
(To build Tamarin-central on Mac please see previous cross-platform instructions here: https://developer.mozilla.org/index.php?title=En/Tamarin/Tamarin_Build_Documentation&revision=21
The bug when building on Snow Leopard (Bug 537817) has been fixed in the Tamarin-redux repo. The work for that fix also included some changes to the configure.py default behavior to decouple the --target switch from sdk choice:
- There is a new switch, --mac-sdk, that selects the 10.4u, 10.5 or 10.6 sdk. Its options are '104u', '105' or '106' (Note: no '.')
- If you don't pass the --mac-sdk switch you will get no sdk in your build.
- If you pass '--mac-sdk=104u' you will also get gcc/g++ 4.0.
- If you pass '--mac-sdk=105' or '--mac-sdk=106' you will get the gcc/g++ default for the machine you're building on.
Example call to build on an x86_64 machine with the 10.5 sdk:
$ ../configure.py --mac-sdk=105 --target=x86_64-darwin
If ASC is not set, you will need to add ASC.jar to the utils directory in Tamarin-redux (Bug 631641).
- Download ftp://ftp.mozilla.org/pub/js/tamarin/builds/asc/latest/asc.jar
- Put it in utils/
Building Tamarin for Android 2.3.3 on Mac
Public sdk/ndk Setup
To build Tamarin for Android you will need an sdk/ndk. The setup procedure below creates an android sdk/ndk entirely from publicly available sources. This sdk/ndk *must* be used if you've cloned tamarin at changeset 5844:92ad3ca84a0b or later and will be using the cross-compile build method.
Steps to create a public sdk/ndk tree on a Mac:
- Create an sdk/ndk top folder under your main volume named /android-public.
- Download the Android 2.3.3 Mac sdk zip file from http://developer.android.com/sdk/index.html. Unzip to your sdk/ndk top folder. Make sure it's named 'android-sdk-mac_86'.
- Download the r5b Mac ndk zip file from http://developer.android.com/sdk/ndk/index.html. Unzip to your sdk/ndk top folder. Rename this folder to 'android-ndk'.
- Run the Android SDK/AVD Manager at /android-public/android-sdk-mac_86/tools/android and add Android SDK Platform-tools (to get adb), SDK Platform Android 2.3.3, and API 10 (samples and docs are optional). If you have trouble starting the app try this:
$ export ANDROID_SWT=$ANDROID_BUILD_TOP/android-sdk-mac_86/tools/lib/x86_64
where $ANDROID_BUILD_TOP is the full path to your sdk/ndk top folder
- Get the openssl-0.9.8r.tar (openssl-1.0.0c.tar.gz won't work) openssl files from http://www.openssl.org (use the Source link on the left). Unzip the file and put the /openssl main folder under your sdk/ndk top folder. Make sure its name is just "openssl". Then build as follows:
- Replace the Makefile in the main folder with the one attached to this page.
- Change the variable ANDROID_DEVICE in the makefile (near line 65) to point to your sdk/ndk top folder.
- Find the two instances of "android-ndk" and make sure they match your ndk's name (they should already).
- In a terminal window change to your /openssl folder and run make build_libs to create the necessary 'libcrypto.a' and 'libssl.a' static libraries.
Alternatively, run make, in which case the process will complete with errors when it tries to create the shared lib crt0.o:
$ /android-public/android-ndk/toolchains/arm-eabi-4.4.0/prebuilt/darwin-x86/bin/../lib/gcc/arm-eabi/4.4.0/../../../../arm-eabi/bin/ld: crt0.o: No such file: No such file or directory collect2: ld returned 1 exit status make[2]: *** [link_app.] Error 1 make[1]: *** [openssl] Error 2 make: *** [build_apps] Error 1
You can ignore these errors. The necessary static files 'libcrypto.a' and 'libssl.a' are made correctly and are present in the /openssl folder. More information on why this happens on Mac OS is here: http://developer.apple.com/library/mac/#qa/qa2001/qa1118.html
- Create a /frameworks/base/opengl/include/EGL folder under your sdk/ndk top folder. Get the ersion 1.4 EGL header files (egl.h, eglext.h and eglplatform.h) from http://www.khronos.org/registry/egl/ and save or copy them there.
Build Tamarin Release Shell
- Get tamarin-redux
- Export the following variables into the environment
$ export ANDROID_TOOLCHAIN=<full path to your android sdk/ndk top folder> $ export ANDROID_NDK=$ANDROID_TOOLCHAIN/android-ndk $ export ANDROID_NDK_BIN=$ANDROID_NDK/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin $ export ANDROID_SDK=$ANDROID_TOOLCHAIN/android-sdk-mac_86 $ export PATH=$PATH:$ANDROID_SDK/platform-tools:$ANDROID_NDK_BIN
$ hg clone http://hg.mozilla.org/tamarin-redux $ cd tamarin-redux $ mkdir objdir-release $ cd objdir-release $ ../configure.py --arm-arch=armv7-a --target=arm-android $ make
To make a debug shell use this command:
../configure.py --enable-debug --arm-arch=armv7-a --target=arm-android
Using Cross-Platform scripts in CYGWIN on Windows:
Prerequisites: You need Python 2.5 or later and GNU make 3.81 or later. (GNU make 3.80 does not work. Nor does any other brand of make.)
Setup:
- If you normally work in a cygwin mounted place (eg /home/user/...) then you must cd around to the cygdrive path equivalent (eg /cygdrive/c/cygwin/home/user/).
- Setup the shell environment with the following environment variables:
# NOTE: The INCLUDE, LIB and LIBPATH must contain windows path information and separator and not cygwin paths. VS_HOME_PATH="/cygdrive/c/Program Files/Microsoft Visual Studio 9.0" VS_HOME="c:\Program Files\Microsoft Visual Studio 9.0" export PATH="$VS_HOME_PATH/Common7/IDE:$VS_HOME_PATH/VC/bin:$VS_HOME_PATH/Common7/Tools:$VS_HOME_PATH/VC/VCPackages:$PATH" export INCLUDE="$VS_HOME\VC\atlmfc\include;$VS_HOME\VC\include;C:\Program Files\Microsoft SDKs\Windows\v6.0A\Include;" export LIB="$VS_HOME\VC\atlmfc\lib;$VS_HOME\VC\lib;C:\Program Files\Microsoft SDKs\Windows\v6.0A\Lib" export LIBPATH="$VS_HOME\VC\atlmfc\lib;$VS_HOME\VC\lib;C:\Program Files\Microsoft SDKs\Windows\v6.0A\Lib"
With the above setup you should now be able to build:
$ hg clone http://hg.mozilla.org/tamarin-central/ $ cd tamarin-central $ mkdir objdir-release $ cd objdir-release $ python ../configure.py $ make ... $ shell/avmshell.exe shell 1.0 build cyclone ...
Microsoft Visual Studio
Visual Studio 2008 (VS2008) is the preferred Windows build environment. Visual Studio 2003 and 2005 are no longer supported. To build Tamarin:
- copy tamarin/platform/win32/armasm.rules to c:/Program Files/Microsoft Visual Studio 9.0/VC/VCProjectDefaults
- Build "builtin.h" following the instructions below in the section "Compiling and running applications"
- Do the same for shell_toplevel.h, starting in avmplus/shell, using the command "python shell_toplevel.py"
- open the Tamarin project file
platform/win32/avmplus2008.sln. - Choose your desired configuration and target, and build.
- Note: now that bug 478714 has been fixed, the name of the (shell) executable will always be "avm.exe" no matter which build configuration you select. The avm.exe file will be found in a directory reflecting your configuration choice. For example, if you chose the win32 Debug_Debugger configuration your build will be under \tamarin-redux\platform\win32\obj_9\shell\Debug_Debugger by default. Building the x64 Release_Debugger configuration will create avm.exe under \tamarin-redux\platform\win32\x64\Release_Debugger. Note the "\obj9" directory under \platform\win32 for the win32 builds and "\x64" directory under \platform\win32 for 64-bit builds; this looks a little odd but preserves previous behavior as much as possible to avoid initial disruption from the shell rename fix.
You must install VS2008 with x64 support to build the 64-bit configurations.
If you installed the Windows Mobile 6 SDK, you can build for Windows Mobile (ARM) targets.
Apple XCode
The project files are designed for XCode 3.0. See platform/mac/avmplus/avmplus.xcodeproj/. XCode 2.2, 2.3, and 2.4 will not work.
There are two targets in the XCode IDE, 'avm' for 32-bit builds and 'avm64' for 64-bit builds. There is also an aggregate target that will build both targets. Note that, whereas before when you selected the aggregate target you got a 'shell' 32-bit executable and a 'shell64' 64-bit executable in the same folder, now because of the fix to bug 478714 you will get an 'avm' executable in two separate folders, /Debug and /Debug64 respectively.
The command to build from the Terminal is:
$ cd tamarin-redux $ xcodebuild ARCHS=ppc -project platform/mac/avmshell/avmshell.xcodeproj
For a debug build, add '-configuration Debug' (note the capital D and no "="). Additional configurations are: Debug_Debugger, Release and Release_Debugger.
The resulting Debug executable for the command above would be built at /platform/mac/avmshell/build/Debug/avm.
Intel Macs build correctly by setting ARCHS=i386.
Eclipse (currently Mac only)
Eclipse (Galileo) / CDT (6.0) project for Tamarin (also works with Helios).
The configurations in this initial version cover 32- and 64-bit builds for Mac OS with the GCC 4.0 toolchain (installed with Xcode 3.x).
Preparing your Eclipse workspace and perspective
- Open the C/C++ perspective
- Open the 'C/C++ Projects' view (Window >> Show View >> C/C++ Projects)
- Add view filter 'Non-C Elements' (In the top-right of the 'C/C++ Projects' view, click the down-arrow, click 'Filters...', check 'Non-C elements')
- Increase the threshold for 'editor scalability mode' to 20000 lines. As some Tamarin source files have more than the Eclipse standard threshold of 5000, they do not appear as indexed. The threshold can be adjusted in Eclipse preferences >> C/C++ >> Editor >> Scalability.
- *IMPORTANT* Project-specific settings for the CDT Indexer do not appear to work (it looks like a bug in Eclipse), so you have to set these manually/globally. What we want is to have the indexer track the currently selected build config (so the correct conditional compiles are highlighted in the editor). To enable this go to Eclipse preferences >> C/C++ >> Indexer, then select 'Use active build configuration' in the 'Build configuration for the indexer' section.
Importing the project into Eclipse
- File >> Import >> General >> Existing Projects into Workspace
- Click next
- The root directory should be the full path to your top-level tamarin-redux directory
- Ensure the 'avmshell-project' project is checked in the 'Projects' list
- Uncheck 'Copy projects into workspace'
- Click finish
Building in Eclipse
8 build configurations are included for MacOS with the GCC 4.0 toolchain:
- Mac-32-Release
- Mac-64-Release
- Mac-32-Debug
- Mac-64-Debug
- Mac-32-Release-Debugger
- Mac-64-Release-Debugger
- Mac-32-Debug-Debugger
- Mac-64-Debug-Debugger
The build location will be PROJECT_ROOT/BUILD_NAME/avm
Note: As discussed above, the C++ indexer has been setup to track the current build config, so the correct conditional compiles are highlighted in the editor
Run/Debug from Eclipse
For test purposes, a launch config (running the HelloWorld test from esc) has been included for each of the build configs. All are available from the Run menu.
Note: if you receive an error when trying to run/debug a newly imported project, try opening a file in the project first - Eclipse can sometimes get confused as to what the 'current project' actually is. Additional things to try are clicking on the project name then refreshing it (File/Refresh or right-click/Refresh) and/or quitting and restarting Eclipse.
Linux and Unix
Tamarin is tested on Linux but not on other Unix flavors. Nonetheless, it is possible to build Tamarin on Unix.
Execute the following commands to build:
$ cd tamarin-central/platform/unix $ make
The resulting executable "shell" is built in the current directory.
Compiling and running applications
Currently the only compiler for Tamarin is the Adobe ActionScript compiler. The source code for the ActionScript compiler, asc, has been open sourced as part of Adobe Flex®. This compiler is written in Java and will require the installation of a Java™ 1.4 or later JDK.
A prototype self-hosting ECMAScript Edition 4 compiler, esc, is provided with Tamarin but it is not yet capable of bootstrapping itself or building applications. esc is under active development and will be able to generate Tamarin applications later this year.
Use the following steps to build and install the ActionScript compiler.
- Download and build the asc source code using the subversion client
$ svn co http://opensource.adobe.com/svn/open...box/asc-redux/ asc $ cd asc/build/java $ ant ... jar: [jar] Building jar asc\lib\asc.jar $ cd ../.. $ java -jar lib/asc.jar # shows usage
You may also download the latest asc.jar from ftp://ftp.mozilla.org/pub/js/tamarin...latest/asc.jar .
You should now copy asc.jar into tamarin-central/utils.
asc.jar can be used to compile the builtin.abc file. The builtin.abc file provides internal information about the built-in classes (Object, Array, etc). This file is located in the core directory; you shouldn't normally need to rebuild it, unless you edit any of the ActionScript source for the built-in classes. To rebuild it, use the builtin.py script:
$ cd tamarin-central/core $ export ASC=../utils/asc.jar # builtin.py uses this to find asc.jar $ python builtin.py building builtin.abc, builtin.cpp, builtin.h builtin: 26795 Files: 6 Time: 1709ms
You can now use
asc.jar to compile applications.
$ cd tamarin-central
$ echo 'print("hello, world")' > hello.as
$ java -jar ./utils/asc.jar -import ./core/builtin.abc hello.as
hello.abc, 86 bytes written
Use the AVMPlus standalone executable (avmshell) built previously to run the application:
$ avmshell hello.abc hello, world
Use the -help options of asc.jar and avmshell for more details.
Running Tamarin Tests
See Running Tamarin acceptance tests and Running Tamarin performance tests
Building Tamarin Windows Mobile utilities
The Tamarin Windows Mobile utilities allows the existing acceptance and performance testsuites to be run on a Windows Mobile device connected to a Windows desktop machine by ActiveSync or Windows Mobile Device Center (for Windows Vista and Windows 7).
- Setup and run ActiveSync or Windows Mobile Device Center. You should be connected and able to see the devices file system in Windows Explorer
- in tamarin repository go to the utils/wmremote directory, open the ceremoteshell2008.sln file in Visual Studio 2008
- Build all targets in Release mode (for more information see utils/wmremote/readme.txt)
- copy Release/avmremote.dll to the device in the \Windows directory
- export AVM=Release/ceremoteshell.exe, the ceremoteshell.exe behaves as a proxy copying and running abc files on the windows mobile device
- build a windows mobile tamarin shell, copy the shell to the windows mobile device in \Program Files\shell\avmshell.exe
- (optional) Can sanity check the windows mobile shell is functioning by running $AVM hello.abc (where hello.abc is a simple abc to print a string, or can substitute with any test abc)
- Now any acceptance or performance tests can be run as on desktop using test/acceptance/runtests.py or tests/performance/runtests.py
Tamarin BuildBot
Adobe maintains a continuous build and test system for Tamarin Redux, similar to TinderBox.
Tamarin BuildBot TryServer
The TryServer/Sandbox is setup to allow users to push any code changes that they would like to have tested in the automated build/test process prior to actually pushing the changes. The Sandbox is setup so that it is able to build and test branches that are based on either tamarin-central or tamarin-tracing.
Any comments, questions or problems can be directed to
How to
- Setup a user repository with the source and patches that will be compiled. Documentation on how to setup a user repository http://developer.mozilla.org/En/Publishing_Mercurial_Clones. Push any changes that you want to test into this repository.
- Request a build via the form at http://tamarin-builds.mozilla.org/build_trigger/requestbuild.cfm
- User Email: Your email address. An email with the build status will be sent to this address when a builder completes whether it is passes or fails.
- Mercurial Repository: Give the location of the repository that will be used for the build. NOTE: Only repositories hosted on http://hg.mozilla.org/ are accepted.
- Revision: Specify the revision number that will be built. Currently this only accepts the change number and not the hash.
- Branch: Which branch of tamarin the repository is based on, Tamarin-Central or Tamarin-Tracing.
- Description: Self explanatory
- Check the status of the build @ http://tamarin-builds.mozilla.org/tamarin-redux/ , you can also see your build request in the queue at http://tamarin-builds.mozilla.org/build_trigger/requestbuild.cfm. If you no longer want you sandbox to build and it has not started yet, you can delete the build request from the queue from the request page.
TryServer etiquette
The sandbox is not a good substitute for running the regression tests locally to catch obvious problems.
This is a shared resource, each request takes approximately 2+ hours to run so please use wisely.