Overview

The Solution Guide for Migrating UNIX Build Environments contains prescriptive guidance for migrating a software build process from UNIX to Microsoft® Windows®. The migration of a build process usually takes place in the context of a larger application migration project. This solution guide addresses only the build system migration, but it discusses the interdependencies between the build system migration and the application migration, and it identifies the aspects of the two projects that require both coordination in timing and decision-making.

Organizations must make an important initial choice about the build system migration: whether to migrate their UNIX make-based build environment and scripts to Windows or to rewrite entirely their build system using Windows-specific tools. This guide is intended primarily for those who have chosen the first option, although the information it provides about the issues encountered when migrating an existing UNIX software build process based on the UNIX make utility can also help in making the decision.

The guide begins with an introductory chapter that contains background information on the make utility and its purpose, as well as on the equivalent mechanism on Windows. Subsequent chapters guide project teams through the entire migration of a build system, beginning with the initial decisions that need to be made about which technical choices will best accomplish the stated goals of the migration and ending with the steps involved in making the build process available to its users. The structure of this guide follows the phases of a project, with information that supports the major planning decisions concentrated in earlier chapters, and the detailed, procedural information that supports implementation in later chapters.

On This Page

Intended Audience
How to Use This Solution
Solution Overview Diagram
Software Requirements for This Solution

Intended Audience

The Solution Guide for Migrating UNIX Build Environments is intended for two groups. The first audience is the Information Technology (IT) directors, software architects, and senior engineers who are charged with planning a build system migration from UNIX to Windows. Planners will find in the first three chapters most of the information they need to decide whether their migration project should adopt the strategy of migrating a make-based software build system or create a new Windows-based system.

The second audience for this document is the team who must migrate a software build system based on the make utility. The size of the team will depend on the scope of the migration—a minimal “team” might consist of a single person who is responsible for the migration, perhaps a developer. Development is a critical role for this type of project, and indeed, the common perception is that make is only for developers. However, the project (like all projects) will have needs related to testing, program management, user experience, and release management. Those needs must be fulfilled whether the team is a lone developer wearing several auxiliary hats, or an entire team that also includes those roles. Thus, the prescriptive guidance provided in this guide addresses not only the development role, but also other possible audiences involved in migrating make-based environments at different points in the process.

Knowledge Prerequisites

This document assumes that you are broadly familiar with UNIX and Windows operating systems and the general structure of compiled-language programming (typically C or C++ programming in both environments). Specific knowledge of the make utility is recommended.

In performing the actual build system migration, it is critical that someone on the team have detailed knowledge of the existing build system being used with the application or applications being ported as part of the larger application migration project.

How to Use This Solution

This prescriptive guide is a framework, not a cookbook; there are many decisions to make when migrating a make-based build system, and there is no way to cover all possible decisions. In other words, there are too many varieties of the UNIX make utility and possible combinations of utilities and shell scripts for this to be a cookbook for migration. Instead, this guide can make you aware of potential problems and some solutions on a problem-by-problem basis.

The organizational structure of this guide follows a linear, project-based sequence that presents information in the order that it is needed in the project. Information needed for the initial decision-making is in the Envisioning chapter, detailed procedures and scripts are in the Migrating chapter, and so on.

The guidance describes a rigorous process of planning and development that is appropriate for complex projects involving a substantial commitment of resources and time. For small projects, the process's overhead may outweigh the benefits of the process. (The definition of “small” might be any project involving a two-week time commitment of one or two people and fewer than a dozen makefiles; for build system migration, the number of source code files is not as important as the number of makefiles.) If the cost of mistakes, reversing decisions, and backtracking is small, less procedural rigor is appropriate, and the deliverables and process steps described in the guidance can be interpreted according to their purpose instead of adhered to literally. In general, the degree of formality you choose to apply should be commensurate with the risks to the organization of foregoing the formality.

This guide is designed to be used in conjunction with the UNIX Migration Project Guide (UMPG), which is available at

https://www.microsoft.com/technet/interopmigration/sag/unix/umpg/default.mspx

or it can be downloaded from

https://www.microsoft.com/downloads/details.aspx?familyid=541be1b4-c797-44d0-aeaf-64842ef1d310&displaylang=en

The UMPG supplements the technical information in this guide by providing a foundational description of project management best practices for UNIX migration projects. To support and emphasize their parallel use, the guides follow a parallel organization. The UMPG is based on the Microsoft Solutions Framework (MSF), a milestone-based framework for IT projects that defines five distinct project phases. The UMPG is essentially "MSF for UNIX migration projects." In accordance with the previous discussion of risk and rigor, the UMPG is most valuable for complex or large projects that involve significant resources and require coordination with different parts of the organization. For smaller, simpler projects, it can be useful as a way to organize your thinking about the project, but you will probably want to save time and overhead by quickly stepping through some processes and minimizing formal deliverables.

The general "people and process" guidance in the UMPG is separated from the technology and more project-specific guidance provided here to keep this guide as lean as possible. Some readers need to focus narrowly on project tasks, while other readers with project management and team lead responsibilities need to digest the UMPG.

For interested readers, in-depth information about MSF is available on the Microsoft Solutions Frameworks Web site at https://www.microsoft.com/technet/itsolutions/msf/default.mspx.

Note:  Although the two guides are designed to be used together, the UMPG is not necessary if your organization has an alternative project methodology in place. In that case, map MSF phases and team structure to the elements of the organization's methodology. Readers who will use this guide to implement a project should read at least the overview of MSF in the UMPG to familiarize themselves with the MSF Process Model and the MSF Team Model.

As noted in the "Overview" section of this preface, this guide addresses the larger application migration project associated with the build system migration only when clarification of overlapping issues, problems, and considerations is needed. For a comprehensive look at the issues organizations encounter when integrating their UNIX and Windows operating environments, see the UNIX Application Migration Guide (UAMG), which focuses on the core areas of code ports and migrating applications to the Win32 environment. The UAMG is available at

https://msdn.microsoft.com/library/en-us/dnucmg/html/ucmglp.asp.

Organization by Chapter

The Solution Guide for Migrating UNIX Build Environments consists of the following six chapters.

Chapter 1: Introduction. This chapter discusses the basic problems of software construction, how they are solved on UNIX systems, and how they are solved on Windows systems. It also introduces the high-level strategies for migrating the build system to Windows.

Chapter 2: Envisioning Your Build Migration. This chapter includes a list of questions you should answer to choose the right strategy. It provides the basic reasons why a migration of UNIX makefiles might be a part of your migration strategy.

Chapter 3: Planning Your Build Migration. This chapter looks at the technical concerns that govern the choice of a particular UNIX portability environment. The chapter also discusses the choice of compilers and linkers, and it summarizes the differences between the different UNIX-on-Windows products.

Chapter 4: Migrating the Build System. This chapter provides the technical details for converting makefiles, shell scripts, and command lines from UNIX to Windows.

Chapter 5: Stabilizing the Build System. This chapter provides some notes on common problems with testing and revising your migrated build system.

Chapter 6: Deploying the Migrated Build System. This chapter provides guidance regarding deployment.

Document Scope

This document discusses migrating a make-based build process from a UNIX system to Windows. The migration of build processes which rely on machine generation of makefiles is out of scope for this guide, including makefile generators such as imake and makedepend, and other systems, such as jam and scons. However, the philosophy behind the make-based migration can be applied to those as well.

Much of the UNIX information presented in this document is applicable to many different UNIX systems, even though the examples used are from Sun Microsystems Solaris 7 system.

Applications discussed in this document are primarily limited to those based on the C/C++ languages, and the assumption is that these applications are to be built as a Win32 binary on the Windows platform. This document does not deal with the portability of the application in terms of UNIX API dependencies or other system-specific dependencies that the application may have. It is concerned only with the issues of migrating the build system itself. Therefore, this document assumes the application is a strictly conforming ANSI C/C++ application and that potential UNIX API portability issues are not dealt with here.

This assumption is a necessary simplification for guidance in this document. Many UNIX applications are not strictly ANSI conforming and the build process is part of a much larger application migration process. These factors cannot reasonably be discussed in this document, although they tend to significantly influence the decisions made before and during the build process migration. You should keep them in mind.

The single most important premise of this document is that the success of the migration of your make-based build process depends on how portable your build tools are to one of the many UNIX portability environments available on Windows. In this guide, specific examples of portability issues are provided for the three different and popular UNIX environments on Windows products that are discussed in this document. However, the treatment of these issues can also be applied to other UNIX portability environments on Windows.

Document Conventions

This guide uses the style conventions shown in Table 1.1.

Table 1.1 Document Conventions

Monospace font

Monospace bold font

Solution Overview Diagram

This diagram shows the core activities that are specific to the technology of build environments and software build systems. Much of the project-level guidance for a build environment migration is available in the UMPG, and you and you should refer to that guide for more information.

Software Requirements for This Solution

The Solution Guide for Migrating UNIX Build Environments makes reference to the following products and technologies. These products and technologies are not included as part of this solution guide.

• Microsoft Visual Studio® .NET

• MKS Toolkit for Developers or MKS Toolkit for Enterprise Developers

• Microsoft Interix UNIX environment, included with Microsoft Services for UNIX version 3.5

• Cygwin — GNU tools on Windows

• wcc — Windows cc command for the Interix environment. Available from https://www.interopsystems.com

• Interix gmake — GNU version of make for the Interix environment. Available from https://www.interopsystems.com

Download

Get the Solution Guide for Migrating UNIX Build Environments

Update Notifications

Sign up to learn about updates and new releases

Feedback

Send us your comments or suggestions