Populating the Development Environment | Unix Application Migration Guide (Patterns & Practices)

One problem to solve early is how to transfer files from one system to the other.A UNIX-to-Windows migration requires a plan for moving UNIX code to a Windows-based computer. To keep parallel versions of the software running on both platforms, it could also be necessary to move modified files back to the UNIX system from the Windows-based system.

After getting the original source from the source system ” as a code hierarchy, as an export from a source control system, or as an archive ” the build process must also be created and configured. Some testing of the build process is possible, but the test of whether or not the code compiles and links is part of the port or rewrite itself.

This section discusses moving code between systems in general, then it looks at populating the Interix and the Visual Studio environment with the source. Finally,it describes how to construct a build environment in Visual Studio.

General Considerations

When moving source code from one platform to another, look first at the general structure and location of the various files that need to be moved.

UNIX applications typically go in the /usr directory. Many UNIX administrators further segregate system programs from added user programs. Commonly, user programs are added to /usr/local and system programs go in the root, /usr.

Developers of nonsystem programs ordinarily find source code files in /usr/localon the UNIX platform. Within this directory, common directories include:

/usr/local/bin for executable files.
/usr/local/include for header files.
/usr/local/lib for library files.

Source code for user projects is usually added in a hierarchy from a directory based in /usr/local. For example, the source files for the myapp program, which is part of the mysystem application, are in /usr/local/mysystem/myapp.

On UNIX, a developer s working source files are probably in a structure similarto that described for myapp, but in the developer s home directory instead. If the developer accesses these files from net shares by using NFS, then the files may be found in a structure such as /export/home/<user name >/src/mysystem/myapp.

Windows uses different directory structures for project files. First, applications install their shared and read only components to <drive letter>\Program Files. Windows uses a drive letter instead of the single-rooted UNIX file structure. The actual drive letter used varies according to system configuration. A directory forthe primary development tools and several directories for additional systems are usually found under C:\Program Files.

For example, if the developer needs to use development resources from the base system and an add-on service called mysystem, the developer can expect to findthe base development files in C:\Program Files\mysystem and specific source files in C\Program Files\mysystem\myapp. Under each top-level directory, the developer can expect to find a directory for binaries, header files, and libraries, such as:

C:\Program Files\mysystem\bin for binaries
C:\Program Files\mysystem\include for header files
C:\Program Files\mysystem\lib for libraries

For the released (permanent) version of the source for myapp, look in C:\My Programs\mysystem\myapp. Because most installation programs allow the userto customize the name of the top-level directory, these names can vary. However,the directory structure under the top-level installation directory is probably the same.

Finally, the developer needs a space for the working myapp source files. Unlike UNIX, in Windows these files do not go under the same directory tree as the rest of the program files. In Windows, the project files belong in the area allocated for the developer s documents, say, My Documents. By default, this area is C:\Documents and Settings\<user name>\My Documents. Therefore, look for the myapp sources under C:\Documents and Settings\<user name>\My Documents\mysystem\myapp.

Note

When migrating files, remember that the UNIX text file format is different from Windows. Depending on the target environment, Windows files may need to be converted to UNIX, or vice versa. Interix provides the flip utility for these conversions.

For example, the following command changes a UNIX text file to a Windows text file:

 % flip m MySource.C

The following command converts startup files created using Windows Notepad to the UNIX format:

 % flip -u filename

The flip utility also allows the use of wildcards. The programs ksh , make , and awk (with the -f option) can read script files in either the Interix or Windows format.

Exporting Files from the UNIX Environment

After they are placed in a working directory, the source files can be packaged together by using the tar (Tape Archive) UNIX utility. The utility was named when it applied to packing files together on tape. Now, this utility can create a single file that represents a number of files from a common source, which makes tar useful for packing together a project s files. Use the “c option with tar to create the archive, the -r option to add files to the archive.

A file that represents the output of tar is sometime called a tar ball . After the tar ball is created, the developer can compress it by using gz (GNU Zip).

Now the project is ready to copy to Windows. To do this, use one of the following methods :

Use FTP (file transfer protocol) from an FTP server. (For an FTP file transfer, be sure the session is in binary (image) transfer mode before getting the compressed archive file.)
Use file copy from a file server such as Web, network file system (NFS), or server message block (SMB).
Copy from a CD-ROM drive.

A copy can start from the UNIX side or the Windows side. To copy files from one system to another, the administrator needs to allow access to both the source and target systems from the computer issuing the copy commands. When using NFS or CIFS, the remote share needs to be mounted.

Populating an Interix Environment

It should be as straightforward to import an application s configuration, build, and source files into the Interix development environment as it is to move them between two UNIX systems. Applications typically arrive as a compressed or uncompressed tar archive file. (For more information about tar , see the discussion in the previous section, Exporting Files from the UNIX Environment.)

Because Interix integrates with the Windows environment, Interix provides a program group that can start either a ksh or csh shell. To start one of these shells , click Start and then point to either:

Programs , then Windows Services for UNIX , and then click korn Shell .

or
Programs , then Windows Services for UNIX , and then click C Shell .

From the C or Korn shell, the import can proceed.

– To import the application configuration, build, and source files

Change the working directory to /usr/examples with the cd command, and then copy the compressed archive from the CD-ROM drive by typing
```
 % cd /usr/examples % cp /dev/fs/<CD-ROM Drive Letter>/c_count.tar.gz . 
```
(The period at the end of the last line indicates the current directory.)
If the archive currently exists on a network share and the network share has been mounted to a drive letter, move it into the environment by typing
```
 % cp /dev/fs/<drive letter>/<source directory>/c_count.tar.gz . 
```
Enter the ls list directory command:
```
 % ls 
```
Output from this command looks similar to the following:
```
 c_count.tar.gz        win32       gawk        admin      rpc 
```

Uncompress and extract the files from the archive by typing

 % gunzip < c_count.tar.gz  tar xf

Output from this command looks similar to the following:

 % ls COPYING    c_count.tar  config.status  descrip.mms  makefile.in readme    Makefile  changes    config_h.in  getopt.c manifest    system.h  c_count.1  config.cache  configure getopt.h  mkdirs.sh  tags    c_count.c  config.h configure.bak  install.sh  patchlev.h  testing    c_count.lsm config.log  configure.in  makefile  portal

After the files have been extracted from the archive, populating the Interix environment is complete.

Populating a Windows Environment

Using the Platform SDK or Visual Studio, the procedure for populating the Windows environment is almost the same as that described earlier in Populating an Interix Environment. However, the intended location of the source files is similar to C:\My Programs\mysystem\myapp, depending on the name of the system and application subsystem being imported.

Once the tar file or compressed tar file is in the Windows environment, it needs to be unpacked into the local Windows project area. Use a Windows-based version of tar to do this. Systems that include tar include Interix, MKS NutCracker, and Cygwin. A gz archive can be opened on Windows by using the WinZip archive utility.

After the source files are unpacked, the text for the source file may need a minor conversion. In UNIX, the line-feed character (hex 0A) is used to indicate a new line. In Windows, the combination is carriage return (hex 02) and line feed. To determine whether this conversion is needed, open a source file in Notepad. If the source lacks the proper line feeds, then a conversion is needed. A number of utilities can be used for this. One of them, flip , is delivered with Interix. (For more information about flip , see General Considerations earlier in this chapter.)

Migrating Source Under Source Control

Source control systems impose additional requirements on moving the code. First,if the source control system allows both UNIX and Windows clients , then creating the project environment is the main step. In this case, after the Windows project environment is created, the source is moved by simply checking out the source to the appropriate project area.

If the source control system does not allow both clients, however, follow these steps:

Check out the project source from the source control system on UNIX.
Package the source on UNIX.
Copy the source to Windows.
Unpack the source on Windows.
Check the source into source control on Windows.

The remainder of this section walks through these steps by using tools availableon both UNIX and Windows.

First, the source is checked out of the UNIX source control system into a local user s working directory on UNIX. Most code management tools provide facilities for exporting an entire code hierarchy and creating a tar file directly. If this is not the case, the hierarchy must be checked out and then packaged. The steps for packaging, moving, and unpacking the source take place in much the same way as already described in this section.

Once it is moved and unpacked, the source needs to be checked into source control in the Windows environment. From the command line, the administrator can create a project, add the files to the project, and check the files into Visual SourceSafe by using the following commands:

 ss Create $/MySystem ss Add <working directory path>\MySource.C

 ss Checkin MySource.C

The following command recursively retrieves all files associated with the MySystem project in Visual SourceSafe:

 ss Get $/MySystem R

Migrating a Build Environment to the Windows SDK

The Platform SDK can be used to compile and link C and C++ programs without Visual Studio projects. The nmake tool contains the following functions for building a project:

Description blocks

The nmake tool can group dependencies for a specified block of command operations by using a description block. A description block can list dependent source files that need compilation if a source is out of date, for example.
Command blocks

These blocks group commands that perform operations on the dependencies listed in the description block. Execution of the C compiler ( cl ) is an exampleof a command in a command block.
Macros

Macros can be used to represent strings of characters , such as specific compiler options in an nmake file. For example, CC could represent one set of compiler options.
Inference rules

These rules infer dependents for targets, such as to update description block targets, even when there are no specified commands in the description block.
Derivatives

Derivatives can be used to preprocess commands in an nmake file. For example,a derivation can specify a macro to process decisions in the nmake file, such asto indicate options for a debug build versus options for a release build.
Dot derivatives

Dot derivatives can be used to set specific redefined options in an nmake file.For example, the .SUFFIXES dot derivative can set the suffixes for inference rule referencing.

Migrating a Build Environment to Visual Studio

The task of maintaining UNIX-style code on the Windows platform must take into account the nature of UNIX applications and build procedures. In UNIX, programs are compiled into object modules. The object modules can be linked into executable files or used to create libraries. Libraries can either be static archives (created with ar ) used to add code to executable files, or they can be shared objects. UNIX normally links by using the C/C++ compilers.

Windows programs are compiled by using the compiler. They are linked as executable files, static libraries, or DLLs.

Table 7.4 compares the UNIX and Windows methods for creating executable files, static libraries, and shared libraries.

Table 7.4: UNIX and Windows File Creation Comparison
File Type	Utility to Create	Command Options
UNIX executable file	Linker (ld)
UNIX static library	ar
UNIX shared library	Linker (ld)	-shared
Windows executable file	Linker
Windows static library	Linker
Windows dynamic library	Linker

To migrate the build environment, use one of the following methods:

Manually recreate the build structure. (See Recreating the Build Structure later in this chapter.)
Use batch builds in conjunction with Visual Studio. (See Using Batch Buildswith Visual Studio later in this chapter.)
Create a custom tool to manage projects and builds. (See Creating a Custom Tool later in this chapter.)

Because each method starts with the UNIX makefile, the first step is to look at the project makefiles to see what information needs to be migrated .

Look at setting and configurations first. To do so, use a makefile to create dependencies and rules that generate the makefile target, usually the linked binary, such as an executable file. In addition to rules and dependencies, macros can be createdto represent variables for the functions to be performed, options for each function, and directory locations. Common examples of macros in a makefile are shown inthe Table 7.5.

Table 7.5: Makefile Macro Examples
Macro	Used For
CC	An alias for the C/C++ compiler.
CFLAGS	The C compiler option setting.
CPPFLAGS	The C++ compiler settings.
LDFLAGS	Linker option flags.
INCLUDE	The directory path for header files.
LIB	Libraries to include at link time.

The CFLAGS, LDFLAGS, LIB, and INCLUDE variables yield the main information needed to create a Visual Studio project on Windows, or to create an nmake file on Windows for a batch build. Makefiles can be viewed by using a UNIX text editor, such as vi . Options can also be extracted by using UNIX text utilities such as grep or awk . In the following example, grep finds the text pattern CFLAGS in the file mymake:

 % grep CFLAGS mymake

Dependency rules can also be expressed in the makefile, as shown in Table 7.6.

Table 7.6: Makefile Dependency Rules
Symbol	Action
:	Target is out of date, depending on the source.
!	Target is repeated as sources are examined.
::	Target is accumulated .

A special type of dependency can be expressed by inference rules. By using these rules, target dependencies can be grouped together by common attributes. For example, a .SUFFIXES rule allows files with a common file extension to have the same dependencies.

Recreating the Build Structure

For small to medium- sized applications, often the easiest way to migrate the project is to create the Visual Studio project manually. Because of their smaller size , this technique is useful for prototype applications. It is especially suited to applications that have dependencies on only a single file tree, with all the sources under a single starting directory.

Larger projects may require another scheme because they have a greater numberof source files and the UNIX build procedure is more complex. A long- term migration goal could be to standardize on the Visual Studio tools. When all applications, including the largest ones, are considered , manually creating and maintaining the Visual Studio projects becomes a daunting task.

Converting an Application Build from aMakefile-Based to a Visual Studio-Based Project

Rogue Wave SourcePro uses a makefile-based build model on all platforms; therefore, it provides a good example of manually migrating a makefile-based project to a Visual Studio project.

To convert an application from a makefile-based build to a Visual Studio-based project, you must ensure that flags passed to the compiler are the same, the necessary #defines are the same, and the required header file and library file paths are properly set in the Visual Studio environment. One way to obtain this information is to run nmake from a command line, and redirect the output to a file. For example, if you use the following command from the command line:

 nmake > exampleBuild.txt

nmake will place the output of the compile and link into the exampleBuild.txt file, provided that there is a makefile (named makefile) in the current directory.

Once you have addressed these issues, you can continue development in the Visual Studio environment. The following is a general step-by-step guide to the process.

– To convert a Rogue Wave application into an MSVC project

Start Visual Studio.
On the File menu, click New .
Select Win32 Console Application (all Rogue Wave examples are console applications), give it a name, and click OK .
Select An empty project and click Finish .
Copy all of the source code files from the example application folder to the project folder.
Under FileView (on the left of the screen), right-click Source Files , click Add files to folder , and select all of the .cpp files copied to the project folder.
Repeat step 6 for Header Files and add all the header files in the project folder.
On the Project menu, click Settings , and then click the C++ tab. At the bottomof the dialog box, you will find a text field for Project Options . You will needto find all of the compile options that were used in the Rogue Wave application example and copy them here. To do this:
- Convert -I < anything > to /I < anything > . If a relative path is used in the application, you need to convert it to an absolute path.
- Convert -D < anything > to /D < anything > .
- Convert other options using a similar format; for example, -GX becomes /GX , and so on.
On the Project menu, click Settings , and then click the Link tab. Select Input from the drop-down list at the top of the dialog box.
1. Find an -L < anything > from the Rogue Wave example application, and copyit to Additional library path by entering < anything > .
2. Find the list of all libraries used in the example application, and copy the library names under Object/library modules . Remove any pre-existing library names.
Compile the project. If you receive error messages about conflicting compiler options, then the options cited in the error message were not found in the Rogue Wave example application. Remove any unfound options.

Using Batch Builds with Visual Studio

Creating a Windows nmake file is similar to creating a Visual Studio project. However, creating a Windows makefile is different. When the Visual Studio IDE creates a project, it automatically generates a Windows makefile suitable for use with a batch build. You can also use a Windows text editor, such as Notepad, to create a project manually.

Although a batch build system can manage both the build process and the dependencies for a source code base with hundreds or thousands of files, in such a system it is often difficult to debug a single suspected problem file.

Creating a Custom Tool

To avoid the drawbacks of creating a project manually or using a batch build, a possible solution is to create a tool. A custom tool can drive the Visual Studio COM Automation model to automatically create Visual Studio projects. Equipped with such a tool, a developer can create a project that builds the required sources in debug while the rest of the project remains in release. The tool can accomplish this without manually changing an existing Visual Studio project or creating a new one.

Such a tool requires the following:

A database of source files and dependencies. The UNIX makefile for a typical batch build is the logical starting place for this information. A simple database can be created by parsing the makefile and generating XML to store the resulting information.
A batch script that uses the source dependency database to drive the Visual Studio COM Automation interface. Windows Script Host provides all the capabilities necessary to access data in XML and to use the automation model.
A developer familiar with the Visual Studio COM Automation model must be available to create the batch script.

Although using this strategy can slow build times, it should increase developer productivity. The gain will be proportional to the size of the application source base: The larger the base, the greater the gain.

This strategy is also recommended when UNIX is to remain the primary development environment. The tool can automatically convert UNIX makefiles to be used for Windows development. Thus, developers can build the application on Windows and debug cross-platform problems.

In Automation Script for Visual Studio, later in this chapter, a Windows Script Host script uses VBScript and the Visual Studio 6.0 COM Automation model to create a project based on an XML definition. By using scripts like these, an administrator can leverage the interactive debug features of Visual Studio while maintaining a batch build migrated from UNIX.

Managing Cross-Platform Builds

During a migration, some applications may still need to be maintained and builton UNIX. These cases require a cross-platform development and build strategy.

When building an application on multiple platforms, follow these guidelines:

Choose one platform as the main development platform.
Identify and segregate platform-specific code that cannot be easily maintained with compiler directives (#ifdef). It is easier to maintain such code separatelyfor each platform if it is separated into callable modules.
Keep platform-specific code local to its target platform.
Look for libraries that already offer cross platform support, such as mostC runtime libraries and OpenGL cross-platform libraries.
Migrate source to multiple platforms with each release, rather than synchronizing source across multiple platforms.
Use batch builds on each platform. An automated process can usually be usedto move a batch build from one platform to another.
Consider using a cross-platform build utility, such as GNU make .

Ultimately, the effort exerted to create and maintain a cross-platform build environment depends on how often the changes to an application in one platform need to be migrated to another. A quicker migration process may take less effort than a cross-platform build process.