Porting is the process of taking software that runs on one operating system and computer architecture and making it run on another operating system or architecture. In some cases, where the operating systems or architectures are closely related, or when the source code of the software has particularly been designed to be portable, the port really is straightforward: recompile the sources and run the validation tests to verify that the new program operates just like the original.

However, there are usually difficulties in following this straightforward model so there are more steps to the porting process.

The HP-UX Software Transition Kit (STK) tools and documents can help you quickly identify and resolve interoperability problems in your source code and scripts. For more information on the STK, go to:

http://www.hp.com/go/STK

Porting effort and feasability

A good approach to determining effort and feasibility is to examine each aspect of porting and estimate the minimum and maximum effort required to accomplish each task. The minimum effort for a task should be at least as much as that required to accomplish the task on the original platform. Testing, for instance, will probably take as much time on HP-UX as it does on Solaris. To determine the feasibility, make sure each step can be accomplished, and that the maximum effort falls within your resource budget.

The emergence and adoption of standards such as POSIX.1, UNIX 95, and UNIX 98 has led to a convergence in programming APIs. This has greatly reduced the difficulty of porting but has not eliminated it. First, conformance to a standard is an ongoing process of ever closer approximation. Once a high degree of conformance is achieved, the remaining rare discrepancies are often found only after someone doing a port stumbles on an area that may have been ambiguous in the standard or was not exactly covered by a conformance suite, but was nevertheless implemented in different ways on the two platforms. Second, some behaviors were left undefined by the standards. Applications that rely on a particular vendor’s implementation of undefined behavior or on a particular vendor’s extensions to a standard will require additional effort when porting.

	Porting process

The following outline lists the stages of a typical porting project:

	Porting and coding practices

Most of the coding practices in this guide are not specific to any one vendor or operating system. They are simply good, standard coding practices. A number of books are available that cover similar ground. Some of the better ones include:

	Porting services

If you want assistance migrating your application to HP-UX 11i, HP has Partner Technology Access Centers that offer application certification and porting services to ISVs. Visit the Developer and Solution Partner Program (DSPP) Web site at the following URL:

http://www.hp.com/dspp/

	Third-party software and tools

The availability of third-party software is often the biggest obstacle when planning a porting project. You must determine the availability and cost of third-party software for the target operating system. This may include build environment tools, third-party libraries, and automated testing tools. See Table A-3, “HP-UX Porting and Archive Centre Site and Mirrors” for information about tools that are freely available on HP-UX 11i.

	Scripts

All common commands and utilities specified in the POSIX standard are supported by Solaris and HP-UX. Primary differences usually involve options that are supported on one platform but not on the other, the location of files, or environment variables that affect the behavior of a command or utility.

For example, on Solaris the historical behavior and location of a utility was not changed when the utility's behavior conflicted with a standard. A standard-conforming version of the utility is provided in /usr/xpg4/bin. On HP-UX, the utility's location was not modified and the behavior is determined from the UNIX95 environment variable.

	Compiling the software

The following sections discuss language and programming issues you may encounter when compiling your software.

C language

Porting code from Solaris to HP-UX may require changes to the code due to syntax and semantic differences in how the C language is implemented by Solaris versus HP-UX. Both HP-UX and Sun C compilers support ANSI C (ANSI/ISO 9899-1990), which provides a very closely related C on either platform. In addition, K&R C on both platforms is largely similar, but not as close as ANSI C. The cross-platform compatibility of your C source code can be estimated by one of the following strategies:

You can decide whether to make ANSI-related changes to your source code based on which approach will give you fewer problems.

C++ language

Sun C++ versions 5 and higher implement the same ANSI C++ standard as HP's aC++ compiler, although aC++ generally implements that standard more completely. Language differences should be minimal.

GNU C/C++ language

The GNU Compiler Collection (gcc) is available for Solaris and HP-UX 11i. If your application is currently using gcc on Solaris, continued use on HP-UX 11i will make your migration easier. However, performance-sensitive applications should give serious consideration to using the native HP compilers as the resulting executables will most likely have significantly better performance than the same application built with the GNU Compiler Collection. See Table A-3, “HP-UX Porting and Archive Centre Site and Mirrors” for information on where to obtain GNU tools for HP-UX 11i.

Java language

The HP-UX SDK for the Java platform provides the Java 2 programming tools and run-time environment which allow you to deploy Version 1.4 technology with the best performance on HP-UX 11i systems.

Programming pitfalls

The following practices can create additional work that will need to be done to successfully port your application:

Threads

HP-UX 11i v2 supports the MxN thread model. This model provides the following features:

If you use Sun's POSIX threads, the effort to port to HP POSIX threads will be minimal, if any. If you use proprietary Sun threads, HP recommends that you change all of your thread-related code. Alternatively, you can use the Solaris Compatibility Thread Library (STL) to port applications that use the Solaris threads API to other systems that have a POSIX threads library. For more information on STL, refer to the Open Source software development website:

http://sourceforge.net/projects/sctl/

See  Chapter 6. Threads and Multiprocessing  for more information on threads.

	Testing and test scripts

The time and expense required to port or acquire testing tools must be factored into the porting assessment. If you have developed automated test tools, then these tools will need to be ported to HP-UX 11i. If you are using testing tools provided by a third party, then you will need to check on the availability of these tools on HP-UX 11i. Manual test procedures should be reviewed to ensure the steps and commands are the same on both systems.

	Debugging

Debuggers are different on HP-UX and Solaris, but they have much of the same functionality. The main debugger on HP-UX is WDB, which is an HP-supported implementation of the GDB debugger. The latest version, WDB 4.2.01, works on programs compiled for the Intel Itanium® architecture. For more information, see  Chapter 5. Other development tools .

	Optimization

Because Solaris and HP-UX both conform to many of the same industry standards, you are presumably porting to HP-UX for its reliability and performance. Optimization is therefore an important step in the porting process, and will allow you to take full advantage of your HP platform. Optimization can be as simple as using the appropriate compiler flag or as complex as performing a comprehensive performance analysis using HP Caliper.

Thread analysis and performance analysis tools are different on HP-UX and Solaris, although they have much of the same functionality. Your porting staff will require some time to familiarize themselves with each new tool. For more information, see  Chapter 6. Threads and Multiprocessing .

	Packaging

If you have a software package that is distributed to multiple sites, you may want to package it in HP-UX Software Distributor (SD) format, which allows you to manage the software with the SD software management toolset. For more information on packaging in SD format, see Chapter 10 (Creating Software Packages) in the Software Distributor Administration Guide for HP-UX 11i or by accessing the swpackage(1M) manpage. These documents and additional information can be found at the product’s Web site:

http://h20293.www2.hp.com/

In addition, the Software Depot Cookbook can be found at:

http://docs.hp.com/en/SD/cookbook.html

A new application called Software Package Builder (SPB) is available to help you create a Product Specification File (PSF) that is required for packaging in SD format. HP delivers SPB as a customer selectable software for all operating environments beginning with the HP-UX 11i v2 release and the HP-UX 11i v1 September 2003 release. Additional information on SPB can be found at the product’s Web site:

http://software.hp.com/products/SPB/

The RPM format is another package format to consider. RPM is not supported on either Solaris or HP-UX 11i, but it is available for both. RPM is not included with HP-UX 11i. For more information on RPM, go to:

http://www.rpm.org/

	References

 Appendix B. Porting Checklist  provides a porting checklist to help you start the porting process. For detailed methods on how to plan a port, see the HP-UX Software Transition Kit at:

http://www.hp.com/go/softwareinfo/STK

For the Solaris to HP-UX Software Transition Kit, see:

http://devrsrc1.external.hp.com/STKS/

This chapter provides an overview of the development environment for HP-UX 11i v2.

Standards comparison

HP-UX conforms to many common standards. Table 2-1, “HP-UX and solaris standards” provides a comparison of standards conformance between HP-UX and Solaris.

	Compiler overview

This section provides an overview of the compilers supported on HP-UX 11i:

Table 2-2, “HP-UX 11i compilers” provides an overview of these supported HP-UX 11i compilers.

To verify the product number and version for your compiler, enter the /usr/bin/what (or cc -V) command. For example:

% what /opt/aCC/bin/aCC

/opt/aCC/bin/aCC: 
  HP aC++/C for Itanium®-based systems B3910B 
A.05.50 [May 15 2003] 

	Note: The HP compilers must be purchased seperately; no compiler is included with the base operating system. Licensing is enforced at install time.

HP aC++ and HP ANSI C/C89 compilers

The HP aC++ compiler for Itanium® systems, A.05.50, supports much of the ISO/IEC 14882 Standards for the C Programming Language (the International Standard for C++). When invoked as a C compiler, it supports the American National Standard for Information Systems – Programming Language C, ANSI X3.159–1989 (the ANSI C 89 standard). The compiler also provides partial C99 compliance when used in C mode. The K&R compilation mode is not available with this compiler.

Beginning with HP-UX 11i v1.6, C language compilation support has migrated from the HP C compiler to a common HP aC++ compiler, which compiles both C and C++ source code. As a result, the bundled C compiler in /usr/ccs/bin/cc_bundled is replaced with a driver that invokes the HP aC++ compiler in ANSI C mode.

	Note: The C and C++ compilers are still packaged and installed separately.

In addition, the C89 compiler has also been integrated into HP aC++. There is no merged C and C++ compiler on HP-UX 11i v1.

Included with HP-UX 11i v2 is the librwtool_v2 library, which corresponds to Rogue Wave’s Tools.h++ version 7.1.1. Older versions of the Tools.h++ library are available with versions of HP-UX prior to HP-UX 11i v2. With the librwtool_v2 library, you can use the functionality of Tools.h++ in C++ applications compiled for use with the -AA option (the option that selects the Standard C++ run time, as opposed to the classic C++ run-time. Previously, the functionality of Tools.h++ was only available to programs that were compiled for the classic C++ run time (-AP). To use this library with -AA, link with -lrwtool_v2.

The transition link from /usr/bin/cc may be removed in the future. Therefore, HP recommends that you include the contents of the /etc/PATH file in the PATH variable of your shell.

The HP aC++ header files are now delivered as part of the HP-UX 11i v1.6 and higher operating systems. This is done to facilitate users who wish to use the GNU compiler (gcc) without installing the HP aC++ compiler.

For more information on HP aC++, go to:

http://www.hp.com/go/hpc++

HP C/ANSI C developer’s bundle

The C compiler on HP-UX 11i v1 is a separate product from the C++ compiler. The compiler supports both ANSI C (C89) and K&R dialects as well as partial C99 compiliance. For detailed documentation on the compiler, go to:

http://docs.hp.com/hpux/dev/index.html#c

For information on the HP C/ANSI C developer’s bundle, go to:

http://www.hp.com/go/ansic

Java 2 platform

The Java 2 Standard Edition (J2SE) products for HP-UX 11i provide solutions to develop and deploy Java applications with the best performance on HP servers and workstations. As a Java licensee, the HP releases of updated SDKs closely follow the releases of new versions of the SDK by Sun Microsystems. The latest Java 2 release for HP-UX 11i v2 at the time of this writing is SDK Version 1.4.2.03, which supports the HotSpot virtual machine and includes the Run Time Environment (RTE).

The default virtual machine (VM) for Java on the HP platforms is 32-bit VM. You can enable the 64-bit Hotspot VM using the -d64 flag on the command line. This option is not available on Java versions prior to 1.4.1.

For current information on the latest Java SDK and RTE releases as well as Java development tools, browser plug-ins, and enhancements on HP platforms, go to:

http://www.hp.com/go/java

FORTRAN

The FORTRAN compiler for HP-UX 11i v2 is HP Fortran, which conforms to the Fortran 95 (ISO/IEC 1539-1997) language standard. It leverages the Edinburgh Portable Compiler (EPC) f90 frontend and supports the full OpenMP V2.0 language standard.

The HP Fortran compiler provides a common source base for all HP-UX 11i v2 operating systems, and supports user directives to guide explicit data prefetching, compile-time inlining, and common math library functions. The compiler is complemented by the high-performance math run-time library and a linear algebra package (assembly coded). It is validated against all major Mechanical Computer Aided Engineering (MCAE) applications.

HP Fortran Version 2.7 for HP-UX 11i v2 contains performance-tuning enhancements. To display the product number and the release version of your HP Fortran compiler, enter the what command:

% what /opt/fortran90/bin/f90

/opt/fortran90/bin/f90:
  HP F90 v2.7 
  HP-UX f90 B.11.23.%58 (Itanium-based host and target)
  Wed Jan 15 13:07:14 2003 CST

To read the online release notes for HP Fortran, go to:

http://docs.hp.com/hpux/dev/index.html#Fortran

They are also available in the /opt/fortran90/newconfig/RelNotes/ directory.

For information on HP Fortran for HP-UX 11i, go to:

http://www.hp.com/go/fortran

COBOL

Micro Focus provides a native COBOL compiler, Micro Focus Server Express V2.2, for HP-UX 11i and HP-UX 11i v2. Existing applications compiled with Server Express for other UNIX platforms can be made available on HP-UX without source code modification. For product information, go to:

http://www.microfocus.com/

Acucorp, Inc., an international provider of legacy extension solutions for COBOL applications, provides support for Sun Solaris and HP-UX 11i with their Extend Product Suite. The object files produced by ACUCOBOL-GT are 100 percent portable across all platforms.

For more information on the Acucorp COBOL product offferings, go to:

http://www.acucorp.com/

For more information on COBOL for HP releases, go to:

http://www.hp.com/go/cobol

	Header file and system library paths

On HP-UX 11i, the /usr/include/ and /opt/aCC/include*/ paths contain the primary header file trees. By default, these paths are searched by the C and C++ compilers. The aCC software package is optional. It includes the -fast option that selects the optimum combination of compilation options for speed.

Table 2-3, “Header file paths” lists the header file paths and their descriptions.

System libraries are usually kept in the /usr/lib path. When dynamically linking, the linker uses the .sl, or shared libraries. Shared libraries are versioned with a numerical suffix. The .sl library is typically a link to the latest library version. The /usr/lib directory contains links to the development versions of the X11 and Motif libraries. To link with Motif 2.1 and/or X11 R6, the only link path you need is -L/usr/lib. Table 2-4, “64-Bit library paths” and Table 2-5, “32-Bit library paths” list the library paths and their descriptions for 64- and 32-bit library paths, respectively.

	Patches for HP-UX

You may obtain HP-UX patches in several different ways:

When installing software on your HP-UX 11i system, be sure to read the release notes for each software component you install, and verify that the recommended and required patches are installed. Software packages currently installed on a system can be listed using /usr/sbin/swlist. Check the patch-related manpages for more information: swlist(1M), swinstall(1M), and swremove(1M).

For a document describing HP’s patching process for HP-UX 11i, go to:

http://devresource.hp.com/drc/STK/docs/archive/hpuxpatching.jsp

Both Sun and HP provide C and C++ compilers in an optional software package that can be purchased from the respective companies. By default, the optional compilers for Solaris are installed under /opt/SUNWspro/bin and the optional compilers for HP-UX are installed under /opt/aCC/bin. The information in this chapter refers to these compilers rather than the BSD Compatibility Package C compiler on Solaris and the bundled C complier or the ANSI C compiler on HP-UX.

This chapter discusses porting considerations for the C and C++ compilers available for Solaris 8 and HP-UX 11i v2. The HP-UX 11i v2 compilers all generate 32-bit objects by default so it will be to use the +DD64 compiler option to build a 64-bit program.

C compilers

Both Sun and HP C compilers support the ANSI C (ANSI/ISO 9899-1990) standard. Write your code in strict conformance with ANSI C whenever possible to provide the greatest level of portability, and the most consistent behavior across all platforms.

The C compiler on Solaris and the C compiler on HP-UX can generate either 32-bit ELF objects or 64-bit ELF objects. The default on both operating systems is 32-bit ELF objects. On HP-UX, use the +DD64 compiler option when compiling 64-bit applications.

For more information on the HP C compiler, refer to the HP ANSI C Online Help and Release Notes:

http://docs.hp.com/hpux/dev/index.html#C

For more information on the compilers, refer to the aCC/cc(1) man page.

Language differences

The HP-UX 11i C compiler, in its default mode (-Ae), supports ANSI C with HP extensions. The Sun C compiler, in its default mode, supports ANSI C plus K&R C compatibility extensions. This means that ANSI C is not strictly enforced in the default mode. If you use the Solaris -Xa option or no option, the degree of compliance in your code with the ANSI standard may vary. If there are K&R C extensions in your code, you have at least two possible strategies:

Default behavior

The default behavior of each compiler differs slightly. Table 3-1, “Compiler behavior differences” lists several behaviors that are the default on one compiler, but require an option on the other compiler.

C compiler options

Table 3-2, “Solaris and HP-UX C compiler options” provides quick references for comparing HP and Sun C version 5.5 compiler options.

C compiler options equivalent

Table 3-3, “Solaris cc options and their HP-UX equivalent” lists the Solaris and HP-UX cc options that are the same, the Solaris cc options that have no HP-UX equivalent, and the Solaris cc options that are not required or needed.

	C++ compilers

The Sun and HP C++ compilers both support the ANSI/ISO/IEC 14882-1998 standard. Write your code to be in strict conformance with ANSI C++ whenever possible to provide the greatest level of portability, and the most consistent behavior across all platforms.

For more information on the HP C++ compiler, refer to the HP aC++ Programmer’s Guide and Release Notes. Go to the documentation link on the HP aC++ Home Page:

http://www.hp.com/go/hpc++

Language differences

The Sun and HP C++ compilers both support ANSI C++ in their default modes. For HP aC++, use the -Aa option to enable ANSI C++ standard features like Koenig lookup and standard scoping rules for variables declared in conditional statements like for loops.

If the -compat=4 option is used, or Sun C++ compiler Version 4.x is used, no corresponding compatibility mode exists on the HP aC++ compiler, and changes to the code may have to be made.

Default behavior

The default options for each compiler differ slightly. The most notable differences are the same as those for the C compilers (see Table 3-1, “Compiler behavior differences”).

C++ compiler options

Table 3-4, “Sun and HP C++ compiler options” provides a quick reference that compares the HP and Sun C++ compiler options. The C++ compiler for HP-UX is aCC; the C++ compiler for Solaris is CC.

Templates

Template features of the HP and Sun C++ compilers are very similar. Both allow template specializations and template arguments to be omitted when the compiler can infer them. The default instantiation mechanisms operate in a similar manner. Explicit instantiation through a template declaration works the same. However, there are a few differences that arise from differing degrees of implementation of the ANSI standard.

Sun C++ 5.x recognizes the typename keyword, but does not implement it or enforce its use. HP aC++ implements and enforces the use of this keyword.

In a template, a name with a parameter-dependent qualifier is not taken to be a type unless it is explicitly declared as one with the typename keyword. Because typename is not implemented by the Solaris compiler, it may be used where it is not allowed, or may not be present where required. The best way to fix typename problems when porting is to adhere to the ANSI standard. This will provide the most robust code and allow you to compile on both platforms.

You need to explicitly declare a type or a member function type using the typename keyword when all of the following are true:

If you are implementing a library that provides templates, you may need to instantiate the whole template instead of just those parts referenced. With the Sun C++ compiler, you do this through explicit instantiation or through the -template=wholeclass command-line argument. With the HP aC++ compiler, you do this through explicit instantiation.

If you rely on a template repository, the template instantiation mechanism on Solaris uses a repository. If you referred to a template repository, or the directories Templates.DB, SunWS_cache, SunWS_config, or specifically the file SunWs_config/CC_tmpl_opt or used CCadmin -clean to clear the repository, you will not need to do this on HP-UX. Use explicit instantiation instead.

Other template variations may include but are not limited to:

The HP aC++ compiler allows non-type template arguments in accordance with the ANSI standard, but the Solaris C++ compiler issues an error message

Exception handling

Exception handling is very similar, including the standard exception classes. If you used -noex or -features=no%except on Solaris to disable exception handling, use +noeh to disable exception handling on HP-UX.

Other compiler issues

Sun C++ supports covariant return types on virtual functions. HP aC++ does not support covariant return types with multiple inheriting types. Future errors generated by the aC++ compiler indicate code practices that are not ANSI compliant, or not yet strictly enforced. Such errors indicate problems with the code that will become compile-time errors when that portion of the ANSI standard is enforced. These errors should be fixed.

	Compiler directives and name spaces in HP C

The ANSI C standard specifies exactly which names (for example, variable names, function names, type definition names) are reserved. The intention is to make it easier to port programs from one implementation to another without unexpected collisions in names. For example, since the ANSI C standard does not reserve the open identifier, an ANSI C program may define and use a function named open without colliding with the open(2) system call in different operating systems.

Name space implementation is very similar on both platforms.

HP header file and library implementation of name spaces

The HP header files and libraries have been designed to support several different name spaces. On HP-UX systems, five name spaces are available:

The HP library implementation has been designed with the assumption that many existing programs will use more routines than those allowed by the ANSI C standard.

If a program calls, but does not define, a routine that is not in the ANSI C name space (for example, open), the library will resolve that reference. This allows a clean name space and backward compatibility.

The HP header file implementation uses preprocessor conditional compilation directives to select the name space. In non-ANSI mode, the HP-UX name space is the default. Table 3-6, “Name space selection in ANSI mode on HP-UX” provides information on how to select a name space from a command line or from within a program using the defined libraries on HP-UX.

In ANSI mode, the default is the ANSI C name space. You can use the macro names _POSIX_SOURCE, _XOPEN_SOURCE, and _HPUX_SOURCE to select other name spaces. The name space may need to be relaxed to make existing programs compile in ANSI mode. To accomplish this, define the _HPUX_SOURCE macro. Also, _HPUX_SOURCE is defined if the -Ae option or default option is used.

	Architecture-Specific issues

By default, both the Sun and HP-UX compilers build an executable for the platform on which the executable is compiled. The compilers on Itanium®-based systems generate executables appropriate for all Itanium®-based systems. Based on your customer support requirements, you may want to change these defaults.

If you expect your program to run only on the platform on which you are compiling, you do not need any additional compilation options. If you are compiling your software on a system and wish to have your software run on older HP platforms, use the +DAarchitecture option to designate which platform/processor for which to build your executable. Possible values for this option are:

The +DA option is not required for Itanium®-based systems. Use the model command to determine the model number of the current platform.

Use the +DSmodel option to specify which instruction scheduler to use for the executable. Unlike the +DA option, the +DS option will not prevent executables from running on older implementations than the one specified. The default is to use the instruction scheduler for the architecture indicated by the +DA option, which by default is the architecture of the build system, and the generic case on Itanium®-based systems.

The model can be one of the following:

Refer to the HP-UX system file /opt/langtools/lib/sched.models for a detailed list of model numbers and processor names.

On Itanium®-based systems, the model can be one of the following:

The instruction scheduler optimization performs the following tasks:

Because there are no compatibility issues, HP recommends that you use the scheduler for the newest processor you intend to support. While it will not allow you to take full advantage of the newer processor features, using the scheduler will provide a performance improvement over not using it when running on newer hardware.

Building 32- or 64-Bit binaries

The HP compilers provide special options to build for either 32- or 64-bit binaries. These options also help the linker find the right libraries and toggle the appropriate changes in header files. You can compile 64-bit applications on a 32-bit platform, but they cannot be executed or debugged. On a 64-bit platform, either 32- or 64-bit applications may be compiled and debugged.

The default behavior on HP-UX is to build 32-bit binaries. This can be explicitly enforced by using the +DA2.0N, +DA1.1, or +DD32 options. Building a 64-bit binary requires special options, +DA2.0W or +DD64, which must be used on all source files. All source files and libraries must be compiled in the same manner, and it is not possible to mix 32- and 64-bit objects within an executable.

Access to 64-bit HP-UX information from 32-bit applications should use pstat wrappers or macros (not /dev/kmem). For 32-bit applications, use nlist64 for executable symbol table information.

There is a new option to shmget for 64-bit applications, IPC_SHARE32, which must be used to indicate that a shared memory segment for a 64-bit application will also be shared with 32-bit applications. You do not need this option for 32-bit applications. The mmap interface also has a similar option, MAP_ADDR32, to map shared files between 32- and 64-bit processes.

The HP-UX Software Transition Kit (STK) tools and documents can help you quickly identify and resolve potential 32- and 64-bit interoperability problems in your source code and scripts. For more information on the STK, go to:

http://www.hp.com/go/STK

	Optimization

HP and Sun compilers offer similar levels of optimization. Optimization is performed primarily by the compiler backend, so it is virtually the same for both the C and C++ compilers on each platform. Sun compilers offer five levels of optimization through the -xOn option where n is 1-5. HP compilers offer five levels of optimization through the +On option where n is 0-4. When porting from Solaris to HP-UX, two additional optimization options may be helpful:

Table 3-7, “Compiler optimization - levels and descriptions” provides a comparison of optimization levels. Note that each level includes all the optimizations of the previous level. Although the optimization levels of Sun and HP compilers are not identical, they are substantially similar.

Note that -O is a synonym for "-xO2 or -xO" for Solaris as it is for HP-UX.

The ld link editors on HP-UX and Solaris differ significantly, as is shown most clearly in the number and semantics of command-line options. This chapter provides tables that describe all of the available options to help you port your link commands and to optimize your applications. Differences in shared library versioning and run-time link editing are also discussed. You will find helpful hints and advice to help your port go as smoothly as possible.

The term linker is generally used in this document to refer to the link editor.

Linking your application on HP-UX

This section describes a methodical approach for porting your application to link on HP-UX. Since changes in linker options can cause significant changes in application behavior, allow time to test your application thoroughly. Avoiding link-time errors is important, but not enough to assure a successful port.

For more information on linking your application on HP-UX, see the HP-UX Linker and Libraries Guide:

http://docs.hp.com/en/B2355-90730/B2355-90730.html

	Background information on linker differences

The HP-UX 11i linker provides the following new features:

Lazy loading of shared libraries

The +lazyload loading is deferred until a reference is made to that library during execution. Both the +lazyload and +nolazyload options may appear on the link line at the same time. For lazy loading of libraries, a library must not be:

The linker will silently convert such libraries into +nolazyload libraries.

Dependent libraries of +lazyload shared libraries will not be processed during link time, unless they are explicitly specified on the link line.

Direct binding support

The -B direct option creates a direct link between symbol references and shared libraries by recording the name of the resolved shared library during symbol resolution. This information is used during run time to quickly resolve symbols without searching through all currently loaded libraries.

HP-UX 11i v2 introduces some new symbol resolution binding controls for shared libraries. Three options are available for direct binding: on, off, and lazy; the default is off. Direct binding (-B direct) records the library name from which each symbol is resolved. This improves startup time by allowing the loader to resolve the symbols quickly rather than searching through all loaded shared libraries. Disabling direct binding (-B nodirect) will record only a hint for use later by the loader, which will attempt to resolve the symbol by searching all loaded libraries. The final option, -B lazydirect, is a combination of the other two. Lazy binding will only record library/symbol pairs (-B direct) for those libraries marked for lazy loading. See the previous discussion of +[no]lazyload.

In porting from Solaris to HP-UX, you will need to thoroughly understand the link command lines in your makefiles. Though a few common options exist, such as -l, -L, and -o, even the option to create a shared library differs between the platforms, as does the suffix of the resulting file (.sl on HP-UX and .so on Solaris). The default shared library suffix on HP-UX 11i v2 is .so.

The HP-UX 64-bit linker links ELF (elf(3E)) files. The object format for HP-UX 11i v2 is ELF, so you can use the +DD64 option to generate LP64 code.

The run-time linker (dld.sl in HP-UX, and ld.so.1 on Solaris) locates and binds shared libraries during program execution. It is used both for shared libraries specified at link time and for shared libraries mapped during code execution.

	Versioning shared libraries

Shared-library versioning provides the capability to change the interface or implementation of a particular shared library. It will not break compatibility with executables or other shared libraries that were linked against an earlier version of that library.

Library-level versioning is done by providing separate files with the same basename but different suffixes, each file representing one of the library versions. This technique is also called external versioning in the Solaris documentation. The linker places the location of the correct version of the shared library inside the executable, which allows the run-time linker to find and use it. There are two forms of shared-library versioning: library-level versioning and internal versioning.

The following example demonstrates the process of library-level versioning for the second version of libfoo.sl on HP-UX 11i v2. Although suffixes differ, the procedure is identical on HP-UX and Solaris.

Note that the option to specify the internal name is +h on HP-UX and -h on Solaris.

The only shared-library versioning supported by the HP-UX linker is library-level (external) versioning. Solaris also supports internal versioning of shared libraries by using mapfiles, where the differences in interface between library versions are defined.

If you are porting a mapfile-versioned library from Solaris to HP-UX, you must use library-level versioning to provide this functionality. Because Solaris mapfile versioning also determines whether symbols are global or local, you will need to use the HP-UX +e, -h, or other ld options to establish symbols as local or global.

Both the HP-UX 64-bit run-time linker and Solaris run-time linker load library dependencies breadth-first. The HP-UX 32-bit run-time linker loads library dependencies depth-first. Note that the HP-UX 32-bit run-time linker loads the library dependencies first. If you use this linker rather than the recommended 64-bit run-time linker, you may see a difference in behavior if you rely on load order for symbol resolution of specific initialization and termination function execution order.

	Run-Time linking

The run-time linker, ld.so.1, is supported on both HP-UX and Solaris. Dynamic run-time linking is done by programmatic library calls.

Table 4-1, “Supported run-time calls” lists the dlopen family of run-time calls that the Solaris and HP-UX 64-bit linkers support.

These calls are used programmatically to locate and bind to shared libraries during execution.

Using dlopen

The dlopen function makes an executable object file available to the calling program. The class of files eligible for this operation and the manner of their construction are implementation-defined. These files are executable objects such as shared libraries, relocatable files, or programs. Note that some implementations permit the construction of dependencies between such objects that are embedded within files.

Compiler option

Include dlfcn.h and use the CC command line option -ldl .

Initializers and terminators

Use the init/fini functions. Initialization functions for dependent shared libraries are run in reverse load order on HP-UX. Initialization functions are run in reverse topological order on Solaris. When shared libraries are unloaded, termination functions are run in forward load order on HP-UX and forward topological order on Solaris.

Binding modes and visibility

Binding can be RTLD_NOW or RTLD_LAZY, indicating when function symbols are bound: when loaded or when first referenced from the executable. The default is RTLD_LAZY.

Default visibility of symbols in a library loaded at run time is RTLD_LOCAL, which means that only libraries loaded at the same time can see the symbols. Visibility can be made RTLD_GLOBAL in the dlopen call. Solaris also supports the following:

Other Solaris options that can be specified are:

Specifying search paths for the run-time linker

There are a number of different ways to specify search paths used by the run-time linker. Table 4-2, “Comparison of specifying search paths” summarizes the steps taken by the run-time linker to search for run-time loaded libraries. As soon as an appropriate library is found, the run-time linker stops searching.

In Table 4-2, “Comparison of specifying search paths”, the HP-UX 64-bit column describes the HP-UX 64-bit linker +std behavior; the +compat behavior is the same as the HP-UX 32-bit linker. The HP-UX 32-bit linker embeds the full path to the shared library in the program. This means you must be cautious about moving the shared library after the program is linked.

Be careful when specifying a relative path for the Solaris and HP-UX 64-bit linkers. Recall that the program may be executed in a different file system location from where it was linked. HP recommends using either full paths or basenames with one of the previous search methods.

	Linker-related tools

Table 4-3, “HP-UX linker-related tools” and Table 4-4, “Solaris linker-related tools” show a variety of tools that are available on either platform to analyze and modify shared libraries and executables. The HP-UX chatr tool is particularly useful to modify attributes of executables or libraries without relinking.

Solaris also has the following linker support libraries, which you can use to debug difficult linker problems: ld-support, rtld-support, and rtld_debugger.

	Passing options to the linker

The following general problems can occur when you develop link command lines for your makefiles:

There are a couple of techniques to overcome these problems, which are discussed here.

Solving the compiler problem

Both Solaris and HP-UX compilers support sending options directly to the linker without being interpreted by the compiler. On HP-UX 11i v2, this is done by using the -Wl,option, which can appear as many times as needed on the command line.

The Solaris linker reads values from the LD_OPTIONS environment variable, which allows you to pass values into the link step that would otherwise cause errors or unwanted behavior from the compiler. The HP-UX linker reads the LDOPTS environment variable instead, for which the setting is put ahead of any command-line arguments.

Solving the command line problem

Both Solaris and HP-UX support reading in options to the linker from a file at link time to avoid problems with an extremely long command line. The option is -c filename. The options file supports comments in the form of lines that start with #, which can be very helpful in documenting linker options. You may want to use the file technique to document complicated sets of linker options.

	Command-line options

Be careful when porting linker command-line options in your makefiles. A particular functionality can be specified by different flags on the two platforms, and some identical flags perform different functions. In no case does this kind of ambiguity exist between options on the 32-bit and 64-bit linkers on HP-UX. However, some options exist only in one or the other.

Table 4-5, “All Solaris standalone options” through Table 4-12, “HP-UX 32-Bit linker options only with arguments” summarize the command-line options for ld. The tables are arranged specifically for convenience in porting from Solaris as follows:

	Precautions and advice

This section contains several tips to keep in mind as you are porting your applications. Inconsistencies, danger areas, and general suggestions are included.

Watch out for passive symbol definition

Complicated symbol-hiding mechanisms in sets of dependent libraries may fail or need significant work to port to HP-UX. The most fragile are those that rely on undocumented linker behavior. HP recommends simplifying these mechanisms, if at all possible, on all supported platforms.

Decide how you want to export symbols

Specifying -B symbolic causes the HP-UX 32-bit linker to optimize all paths in the library, and also export all functions. The +e epsym option overrides this behavior, exporting only the specified symbol. You can also export all functions with -E. You can hide symbols by using -h sym. It is better not to use both -h and +e in the same command line as it is confusing. You cannot use mapfiles to control symbol exporting on HP-UX.

Do not use the -A and -R options to do dynamic linking

For the HP-UX 32-bit linker, you can use -A and -R to do dynamic linking, but if you use them you will be unable to link with shared libraries. This older method is likely to become obsolete in the near future, and HP recommends that you not use it. The benefits of using shared libraries far outweighs the benefits of using -A.

Do not use mapfiles on HP-UX unless you are a systems programmer

You can use a mapfile to explicitly describe the output file memory layout. This functionality is designed to be used by systems programmers, not application developers. It is specified with the -k file option. You can easily link an executable that will not execute, and the problem can be very difficult to diagnose. Solaris also supports this functionality in mapfiles, specified by -M file. Solaris mapfiles are also used to specify internal library versioning directives, which are not supported in HP-UX.

Note differences in dependency ordering

The Solaris linker figures and uses a topological ordering of libraries during a link, rather than link order as given by -l options on the command line. HP-UX uses link order. Ordering determines when initialization and termination functions for each library are called, as well as the order in which symbol definitions are found. If order is important for the libraries you are porting to function properly, determine the correct order for HP-UX and change the link command as needed. Prior to release 2.6, Solaris performed load-order searching, setting the LD_BREADTH environment variable to a nonzero value will restore this behavior.

Note differences in initializers and terminators

The HP-UX 64-bit and Solaris run-time linkers both support the init/fini style of initialization and termination functions. Initialization and termination functions are identified in the source code with #pragma init or #pragma fini. On the ld command line that links the load module, you need to specify the name of the functions with +init epsym or +fini epsym.

Do not use shl_load and _thread together

On HP-UX, if you use the _thread variable, or thread local storage (TLS) in a shared library, executables will not be able to dynamically load your shared library.

On HP-UX 11i version 1.6, the /usr/lib/hpux64/dld.so shared library is the 64-bit dynamic loader. In programs that use shared libraries, dld.so is automatically invoked at startup time. dld.so supports static and dynamic TLS model shared libraries compiled with the +tls=static and +tls=dynamic compiler options.

Shared libraries built with +tls=dynamic can be loaded using the dlopen and shl_load system calls. Attempting to load a +tls=static shared library results in an error stating that you cannot shl_load, a library containing TLS.

Check for file permissions

An HP-UX shared library should have read and execute permissions, but no write permissions, for fastest binding. For example, ls -l /usr/lib/libc.1 returns:

-rwxr-xr-x   1 root     bin      1158072 Nov  7 00:44 /usr/lib/libc.so.1

Note that your date and size may vary.

Find an alternative to filtering

Solaris supports an explicit "filter" mechanism — a special shared object consisting of a symbol table but no implementation. The -F and -f linker options are used to specify a shared object that contains the definitions for the symbols.

Find an alternative to weak symbols

In Solaris, symbols can be set with a pragma to be weak, which means that these symbols are always overridden by any global definition. If an undefined weak symbol is never satisfied by a global definition, it is set to 0 before the program starts execution. HP_SECONDARY_DEF symbols are similar to Solaris weak symbols, but there are some differences. You can use the _HP_SECONDARY_DEF pragma to connect a weak and a strong definition (for example, _fopen and fopen). The weak definition can be overridden by other strong definitions.

Watch out for reserved symbols

Table 4-13, “Reserved linker symbols” lists some of the reserved symbols for the Solaris, HP-UX 64-bit, and HP-UX 32-bit linkers.

Tools other than compilers are also required for a complete development environment. This chapter discusses some of these other tools frequently used by developers.

Makefiles

Solaris provides three versions of the make command:

HP-UX 11i provides one version of the make command, /usr/ccs/bin/make, which is symbolically linked to /usr/bin/make. The HP-UX 11i make command conforms to the SVID2, SVID3, XPG2, XPG3, XPG4, and POSIX.2 standards. Refer to the HP-UX 11i make(1) man page for more information.

The GNU implementation of make, commonly referred to as gmake, is also available on HP-UX 11i and Solaris. Environments utilizing GNU make on Solaris are encouraged to continue using it on HP-UX 11i. For more information on GNU make and Open Source applications, see  Chapter 9. Freeware, Open Source, Public Domain Software .

HP-UX, Solaris, and GNU makefile similarities

HP-UX, Solaris, and GNU all define the same basic set of suffixes and implicit rules for makefile. The following macros, variables, and options are the same:

Options for the make command

The following options from the Solaris default make command are not available on HP-UX 11i: [-dd] [-D] [-DD] [-V] [-K statefile]. The Solaris make command option -p has different behavior on HP-UX 11i. Table 5-1, “Solaris and HP-UX make option comparison” compares the HP-UX 11i and Solaris make options that are different or unavailable.

If the make command -f option is not used, both Solaris make and HP-UX make command look for makefiles in the following sequence:

Both Solaris and HP-UX assume SCCS as the default for file source control. If the makefile is under source control, then make will attempt to checkout a copy before building.

Special-function targets and make rules

What Solaris documentation refers to as special-function targets, HP-UX documentation calls built-in targets. However, the functionality is unchanged; both platforms provide the .DEFAULT, .PRECIOUS, .SILENT, .IGNORE, .SUFFIXES targets.

Table 5-2, “Solaris special-Function Targets not Available on HP-UX” lists the Solaris special-function targets that are not available on HP-UX.