Part I Installing on the Host

This part describes how to:

• Plan the installation with respect to hardware and software requirements and necessary prerequisites

• Install the Sun Embedded Workshop software for ChorusOS

• Uninstall the product

• Patch the installation

Chapter 1 Planning the Installation

This chapter provides a brief introduction to the ChorusOS operating system, an overview of the installation process, and lists the prerequisites for installation. ChorusOS and its related products are available by means of a web distribution and can be downloaded or a CD-ROM. To download the products, follow the instructions provided by your customer service representative.

• "What is the ChorusOS Operating System?"

• "Overview of Installing, Building, and Booting a ChorusOS System"

• "Host System Requirements"

What is the ChorusOS Operating System?

The ChorusOS operating system is a scalable and reliable embedded operating system that can be deployed on boards of the following supported target families: UltraSPARC IIi/IIe, Intel x86/Pentium, Motorola PowerPC 750/74x0 processor family, and Motorola PowerQUICC I (MPC8xx) and PowerQUICC II (SBC8260) microcontrollers. This operating system is used for the operation of public switches and PBXs, as well as within access networks, cross-connect switches, voice-mail systems, cellular base stations, web-phones, and cellular telephones.

The Sun Embedded Workshop software is used to create and deploy a ChorusOS operating system on a variety of different target boards in the set of target families supported by ChorusOS. Offering high service availability, complete hardware and software integration, management capabilities and Java technology support dedicated to telecommunication needs, the Sun Embedded Workshop software allows dynamic and cost-efficient delivery of new features while maintaining the reliability and functionality of existing networks.

For a more detailed overview of the features and architecture of ChorusOS, see the ChorusOS 5.0 Features and Architecture Overview.

Overview of Installing, Building, and Booting a ChorusOS System

The installation process for the ChorusOS operating system is divided into two parts:

• Installing the Sun Embedded Workshop software on the host.

  The Sun Embedded Workshop software provides the tools necessary to build a ChorusOS system image that can be booted on a target system. This part of the process is covered in Chapter 2, Installing the Sun Embedded Workshop software.

• Building and Booting ChorusOS on a reference target board.

  This includes configuring and building a ChorusOS system image using the Sun Embedded Workshop software, and booting the system image on a target system. This part of the process is covered in Part II, Building and Booting ChorusOS on Target Systems.

The following figure is a map providing an overview of the installation process and shows a few of the possible scenarios for building and booting a system image on the target. These are the different ways described in this guide.

Figure 1-1 Installing, Building, and Booting a ChorusOS System

For flowcharts of target-specific build and boot processes, see Part II, Building and Booting a ChorusOS System.

Host System Requirements

The host system requirements to install the Sun Embedded Workshop software are as follows:

For information on particular target system requirements as well as the ChorusOS packages available with a particular target, see the appropriate ChorusOS 5.0 Target Family Guide.

Chapter 2 Installing the Sun Embedded Workshop Software

This chapter describes how to install the Sun Embedded Workshop software for ChorusOS on a host workstation running the Solaris operating environment. This chapter assumes that you have either a CD-ROM containing the product or have downloaded the necessary files in a download directory such as /home/user/downloads/ChorusOS_5.0 (called the download_dir).

You can install the Sun Embedded Workshop software using one of the following proceduresS:

• "Installing With the Sun Embedded Workshop Graphical Installer"

• "Installing With the pkgadd Utility"

• "Setting Environment Variables"

• "extract.sh Options"

Installing With the Sun Embedded Workshop Graphical Installer

The Sun Embedded Workshop graphical installer is based on the Solaris Web Start Wizards API. To use the graphical installer, you need the superuser password for your system and JDK (version 1.2 or higher). To add JDK to your path, use the following example command:

$ export PATH=/set/java/jdk1.2/bin:$PATH

If you are installing from the CD-ROM, use the File Manager on your desktop to browse the CD-ROM; double-click the installer executable to launch the graphical installer and go to Step 3 of the following procedure.

If you have downloaded the product, go to Step 1 of the following procedure.

To Install With the Sun Embedded Workshop Graphical Installer

1. Create a directory where you have permission and enough space to extract all the files in the delivery.

   The minimum amount of free space required is specified in the section "Host System Requirements".

   $ mkdir extract_dir $ cd extract_dir

   ---

   Note -

   This directory is temporary and will be removed after the installation.

   ---

2. Run the extract.sh script:

   $ sh download_dir/part_number/extract.sh

   ---

   Note -

   For information on the options available with the extract.sh script, use the following command:

   $ sh download_dir/part_number/extract.sh -help

   See "extract.sh Options" for more information.

   ---

3. Enter the superuser password for the host workstation when prompted.

   Please enter this system's root user password. Password: superuser_password

   The graphical installer in this release uses the Solaris package system, including utilities such as pkgadd(1M), to manage installation and dependencies. Solaris package tools require that you become superuser to install packages.

   After initialization finishes, the graphical installer is displayed.

4. Follow the instructions displayed on the Solaris Web Start Wizards screens.

   ---

   Note -

   In the Installation Directory panel, do not choose an NFS directory.

   ---

   If you choose the "Default Install" for a particular target family, the following components of the ChorusOS 5.0 product are installed:

   • The Microkernel component, required to build the microkernel of the system image.

   • The OS component, required to include POSIX-compatible APIs in a system image.

   • The Tools component, required to use the cross-development tool chain for building target system executables on the host workstation.

   • The BSP source files, source files required for board-specific support.

   • The GDB Debugger component, the reference debugger for ChorusOS systems and the Insight graphical interface to GDB.

   • Documentation in PDF and HTML.

   • Online man pages.

5. Exit the graphical installer after you have finished installing the software.

   Log files from the installation are saved in the directory /var/sadm/install/logs.

6. Set environment variables.

   See "Setting Environment Variables".

You may perform the installation procedure as many times as necessary. This is especially useful if you want to install extra components after the initial installation.

If you install any packages of the core delivery, excluding documentation and third-party software, subsequent installations always place files under the install_dir, which is the directory you select during the first installation.

If you decide to reinstall core software packages in another location, you must first remove all the installed packages. See Chapter 3, Uninstalling on the Host, for information on removing installed packages.

Installing With the pkgadd Utility

The pkgadd(1M) allows you to install the Sun Embedded Workshop software as a series of packages on the host workstation. You must have the superuser password for your system.

If you are installing from the CD-ROM, change to the directory containing the packages. For example: /dev/cdrom/part_number/chorus-family/pkgs. Then go to Step 3.

If you have downloaded the product, go to Step 1 of the following procedure.

To Install With the pkgadd Utility

1. Create a directory (extract_dir) where you have permission and enough space to extract all the files in the delivery.

   The minimum amount of free space required is specified in the readme.html. For example:

   $ mkdir extract_dir $ cd extract_dir

2. Run the extract.sh script to extract all the packages:

   $ sh download_dir/part_number/extract.sh -only

   ---

   Note -

   For information on the options available with the extract.sh script, use the following command:

   $ sh download_dir/part_number/extract.sh -help

   See "extract.sh Options" for more information.

   ---

   The packages are extracted and stored in a directory structure similar to this: extract_dir/part_number/chorus-family/pkgs/SUNWxxxx

   where family can be one of the following: mpc8xx, powerpc, usparc, or x86.

3. Install the packages using one of the following methods:

   • To install all the packages for a particular part number together, use one of the following commands:

     • For the downloaded product:

       $ su Password: superuser_password # pkgadd -d extract_dir/part_number/chorus-family/pkgs all

     • For the CD-ROM:

       $ su Password: superuser_password # pkgadd -d /dev/cdrom/part_number/chorus-family/pkgs all

   • To install one package at a time for a particular part number, use one of the following commands:

     • For the downloaded product:

       $ su Password: superuser_password # pkgadd -d extract_dir/part_number/chorus-family/pkgs SUNWxxxx

     • For the CD-ROM:

       $ su Password: superuser_password # pkgadd -d /dev/cdrom/part_number/chorus-family/pkgs SUNWxxxx

4. Set the environment variables.

   See "Setting Environment Variables".

You can perform the installation procedure as many times as necessary. This is especially useful if you want to install extra components after the initial installation.

Setting Environment Variables

Use the information in the following table to set environment variables on the host workstation:

Verify that the environment variables MANPATH and PATH are set correctly, try the following command:

$ man ChorusOSMkMf
Reformatting page.  Wait... done

Misc. Reference Manual Pages                    ChorusOSMkMf(1CC)

NAME
   ChorusOSMkMf - Create a Makefile from an Imakefile for ChorusOS
...
$ ChorusOSMkMf
usage: ChorusOSMkMf build-config-dir|paths-file [-s source-dir]
[-b build-dir] [-d dist-dir]

extract.sh Options

The following options are available with extract.sh:

$ sh installer

Chapter 3 Uninstalling on the Host

This chapter describes how to uninstall the Sun Embedded Workshop software for ChorusOS on the host workstation.

Uninstalling part or all of the Sun Embedded Workshop software depends on the method you chose to install the software. You can use one of the following methods to uninstall the Sun Embedded Workshop software:

• "Uninstalling Using the Sun Embedded Workshop Graphical Uninstaller"

• "Uninstalling With the pkgrm Utility"

Installing with the Solaris Web Start Wizards installer allows you to use either option. You can, therefore, uninstall using either the graphical uninstaller or the pkgrm utility.

Uninstalling Using the Sun Embedded Workshop Graphical Uninstaller

The Sun Embedded Workshop graphical uninstaller is sased on the Solaris Web Start Wizards API. To use the Solaris Web Start Wizards graphical uninstaller, you need the superuser password for your system and JDK (version 1.2 or higher). To add JDK to your path, use the following example command:

$ export PATH=/set/java/jdk1.2/bin:$PATH

Uninstalling Using the Sun Embedded Workshop Uninstaller

1. Change to the directory where the product is installed.

   For example:

   $ cd install_dir/

2. Launch the uninstaller.

   For example:

   $ sh SEW-uninstaller Solaris Web Start uninstaller To use this uninstaller you will need to be the system's root user. Please enter this system's root user password Password: superuser_password Do you want to uninstall SEW for UltraSPARC? y

   ---

   Caution -

   Be sure to enter "y" and not "yes" for the above question.

   ---

   Follow the instructions on the screen to uninstall the product.

Uninstalling With the pkgrm Utility

To remove part or all of the product from the host workstation, use the pkgrm(1M) command line utility.

To use pkgrm, you must know the superuser password for your system.

Uninstalling With the pkgrm Utility

1. See the appropriate ChorusOS 5.0 Target Family Guide for the complete list of packages available for your host/target combination.

2. Verify that the packages you want to remove are installed:

   $ pkginfo | egrep "(Sun Embedded Workshop | ChorusOS)"

3. Become superuser and remove packages using pkgrm:

   $ su Password: superuser_password # pkgrm package_name

Even after all packages are removed, a few HTML files such as README.html and RELEASE.html remain in install_dir. Remove these HTML files manually.

Chapter 4 Patching the Installation

After you install the development environment, you may choose to patch the installation with ChorusOS patches provided by Sun. You manage patches using the patchadd(1M) and patchrm(1M) utilities. See the online manual pages for details on how to use the utilities.

Apply the following patches on your host workstation running the Solaris operating environment before applying patches to ChorusOS:

Solaris 7

Apply patch 107171-04.

Using the standard Solaris tools to manage installations and patches ensures the coherency of the patch management and allows you to track the patch level at any time.

Patches are only guaranteed to work on the original version of the installed product (or patched original versions of the installed product). So you must create a copy of the product source tree if you need to modify it.

Do not manually change an installation of the product.

The ChorusOS configure(1CC) utility detects inconsistently patched installations and refuses to let you build a ChorusOS system image until patch levels for all components involved are equivalent.

When you receive a patch, follow the instructions in the README file provided with the patch. Patches for ChorusOS are direct instance patches, which means that a given revision of a patch for a given product contains the fixes and data of all previous patches for that particular product. Therefore, you don't have to install or remove previous patches.

If you are using add-ons for ChorusOS, such as the Source add-on, make sure that you install the patch associated with the product itself and that you install the patches associated with every add-on package.