This chapter is designed to get you up and running on the ACCESS Linux Platform. These instructions assume that you are installing on a Linux machine running Ubuntu version 6.10 that doesn't already contain a version of the ACCESS Linux Platform. If you install the SDK on Ubuntu version 7.10, the installation procedure might be slightly different.

This chapter describes how to install and configure Scratchbox and the ACCESS Linux Platform SDK. Scratchbox provides a form of host simulation so that the cross compiler can be called simply as "gcc". This greatly simplifies your environment as your configuration appears to be a native configuration rather than a cross configuration.

This chapter contains the following sections:

• "Prerequisites"
• "Installing the Development Environment"
• "Configuring Scratchbox"
• "Uninstalling the Development Environment"

Prerequisites ^TOP^

You can install ACCESS Linux Platform on Ubuntu 6.10 or 7.10.

Make sure that both the main and the universe sections of the repository are enabled:

1. From the Ubuntu menu, choose System > Administration > Software Sources.

   This opens the Software Sources dialog.

2. Make sure that both of the following options are enabled on the Ubuntu 6.10 tab:
   • Community maintained Open Source software (universe)
   • Canonical supported Open Source software (main)

Installing the Development Environment ^TOP^

This section describes how to install and configure the SDK and Scratchbox, which is the development environment used for developing ACCESS Linux Platform and ACCESS Linux Platform applications.

How you install depends upon how the packages were delivered to you. If you have a CD that has a directory named binary-i386 at its root, begin with "Installation from CD-ROM", below. If not, you should have a single file named sdk.tgz (whether or not it is delivered on a CD-ROM is not important). In this case you'll need to start with the instructions under "Installation from Files."

Installation from CD-ROM ^TOP^

To install directly from the CD, complete the following steps.

1. Insert the CD and verify that it contains Packages.gz as well as the following folders:
   • .disk
   • binary-i386
2. From the Ubuntu menu, choose System > Administration > Synaptic Package Manager and enter your password.
3. In the Synaptic Package Manager menu, choose Edit > Add CD-ROM.

   This adds the packages that are listed on the CD to the list of packages available for installation.

4. Verify that the alp-sdk package is available in Synaptic Package Manager, then proceed to Step 7f in the next section, "Installation from Files."

Installation from Files ^TOP^

If the files are supplied as a single tar file (typically named sdk.tgz), you can install from a local directory.

1. Double-click the sdk.tgz file to uncompress it.

   This produces a folder named SDK.

2. Click the SDK folder, then click the Extract button.
3. Navigate to the to /tmp in the Extract in folder field and verify that the All files option is selected.
4. Click the Extract button.

   This extracts the SDK files to the /tmp directory.

5. Close the Extract window.
6. Check the contents of the /tmp directory to verify that it contains the SDK folder:

ls /tmp

7. Now it is time to install the packages. In general, you should install the alp-sdk package to get all of the needed packages at once. If you prefer, you can install the packages individually.
   1. From the Ubuntu menu, choose System > Administration > Synaptic Package Manager and enter your password.
   2. From the Synaptic Package Manager, choose Settings > Repositories.

      This opens the Software Sources dialog.

   3. Click the Third Party tab, then click the Add button.
   4. Enter the path name to the directory where the SDK directory is located, then click Add Source. Note that you must enter the name exactly as shown below:

      deb file:/tmp/SDK ./

   5. Close the Software Sources dialog, and then click the Synaptic Package Manager Reload button.
   6. Right-click the alp-sdk package and choose Mark for Installation from the menu.

      This marks multiple packages for installation in addition to the alp-sdk package. You might see a warning that the software cannot be authenticated. You can ignore the warning and click the Mark button.

   7. Click the Apply button.

      This displays a dialog that summarizes the list of packages to be installed.

   8. Review the list of packages, then click the Apply button at the bottom of the dialog.
   9. Close the Changes Applied dialog and then close Synaptic Package Manager.

      All of the required SDK packages are installed.

8. If you want to be able to access the network from within the ACCESS Linux Platform Simulator, choose the bridge-utils package in Synaptic Package Manager and install it the same way you installed the alp-sdk package.

   Alternatively, you can install it with the following line command:

sudo apt-get install bridge-utils

Note that if you do not install it at this time and try to start the Simulator with the Create host network bridge option enabled (or using the --net option), an error message displays, telling you to install this package. You can wait to install it until you need it, if you prefer; it is not needed for Simulator operations that do not involve the network.

Configuring Scratchbox ^TOP^

1. Add yourself as a Scratchbox user with this command (note that you must use back-quotes, these are not single quotes):

sudo /scratchbox/sbin/sbox_adduser `whoami` yes

If prompted, press Enter at each prompt to accept the default answer.

2. Either log out and then log back in, or use the su command as follows. This allows the group changes (made by sbox_adduser) to take effect:

su `whoami`

3. Run the groups command to confirm that you are now in the "sbox" group.
4. Test your install by logging in to Scratchbox by simply typing scratchbox (which links to /scratchbox/login):

scratchbox

5. If you see the Scratchbox login prompt (the prompt looks something like: [sbox-alp-simulator: ~] >), proceed to "Configuring Your Scratchbox Target".

   If Scratchbox throws an error when you log in, such as:

   ERROR: Scratchbox is not properly set up!

   Check to see if the Scratchbox process is running. Do this by issuing the following commands to stop and re-start Scratchbox:

sudo /scratchbox/sbin/sbox_ctl stop

sudo /scratchbox/sbin/sbox_ctl start

If all is working correctly, the following should be displayed:

Starting Scratchbox: binfmt_misc, mount.

Now you should be able to log in by simply typing:

scratchbox

Configuring Your Scratchbox Target ^TOP^

Once Scratchbox has been configured, you need to set up one or more Scratchbox targets.

Configuring a Simulator Target

1. All of the commands used to configure a target need to be run from within Scratchbox. If you aren't already logged in to Scratchbox, do so with:

   scratchbox

2. Set up the target by running the following command:

sb-conf setup alp-simulator -c i686-linux-gnu

If the command produces the message "sb-conf: No current target", ignore it; the next command selects the simulator target.

3. Select the simulator target with:

sb-conf select alp-simulator

At this point, the screen clears as the shell restarts.

4. Verify the target with the following command:

sb-conf show

It should produce the following:

Compiler: i686-linux-gnu
Devkits: none
CPU-transparency: none

5. Determine the name of the Simulator rootstrap.

ls /scratchbox/ALP/rootstrap/alp-x86-dbg-*

This rootstrap file is used to load the target with prebuilt binaries. Note that because each release of the SDK contains new binaries, the rootstrap name is not static. You need the exact name of this rootstrap file for the next step.

6. Enter the following command to "rootstrap" the target, substituting the actual name of the rootstrap file for the filename (here, alp-x86-dbg-GCC4-main-123456.tar.gz):

sb-conf rootstrap /scratchbox/ALP/rootstrap/\
alp-x86-dbg-GCC4-main-123456.tar.gz

You should see the following message:

Unpacking rootstrap...

The scratchbox environment is now configured, and you can proceed to "Testing the Installation".

If you encountered problems during the installation process, you can find additional information in Chapter 4, "Troubleshooting."

Uninstalling the Development Environment ^TOP^

In the event you need to uninstall the ACCESS Linux Platform Development Suite, these instructions take you through the procedure.

Back Up Your Work ^TOP^

Uninstallation requires you to remove the entire /scratchbox directory. Before performing the appropriate uninstallation procedure, back up any work inside Scratchbox that you want to save. If you are using a source control system such as Perforce, be sure to confirm that you do not have any open (that is, pending or unsubmitted) edits.

Copy or move /scratchbox/users/$USER to some place outside of the /scratchbox directory to keep it safe.

Uninstall ^TOP^

1. Exit all of your Scratchbox sessions. (Type exit to exit a Scratchbox session.)
2. Stop the Scratchbox process with:

   sudo /scratchbox/sbin/sbox_ctl stop

3. You can either remove the packages using the GUI or from the command line:

   To use the GUI:

   1. Start the Synaptic Package Manager with:

      sudo synaptic

   2. Select all of the packages whose names begin with alp-. Note that you can quickly isolate the relevant packages by performing a search from within the Synaptic Package Manager. Then you can select all of the ones whose names begin with alp-.
   3. From the Package menu, select Mark for Complete Removal.
   4. Select all of the packages whose names begin with scratchbox-.
   5. From the Package menu, select Mark for Complete Removal.
   6. From the Edit menu, select Apply Marked Changes. In the dialog that is displayed confirming the operation, click Apply.
   7. Quit the Synaptic Package Manager.

      If you prefer to use the command line, remove the packages with the following commands:

sudo dpkg --get-selections | grep 'alp-'  \
# just to see what will be removed

sudo dpkg --purge `dpkg --get-selections | \
grep 'alp-' | cut -f1`

sudo dpkg --get-selections | \
grep 'scratchbox-'   \
# just to see what will be removed

sudo dpkg --purge `dpkg --get-selections | \
grep 'scratchbox-' | cut -f1`

4. If the /tmp/SDK directory has not been removed by the uninstall procedure, remove it by entering the following command in a shell window:

sudo rm -fr /tmp/SDK

5. In a shell, remove any remaining files with the following command:

sudo rm -fr /scratchbox/*

6. Navigate to your home directory and remove the hidden .alp-dev directory with the following command:

rm -rf .alp-dev

The SDK is completely uninstalled and the system is ready for reinstallation.