Developing AbiWord on Windows using Visual C++

From AbiWiki

You can help improve this page! Link research needed!

Starting places: the rest of the wiki, the main AbiWord web site, the mailing list archives, Google search of abisource.com Researching links is considered an intro-level task due to its generally low difficulty and high potential for project-connected learning on the part of the researcher. If you want to learn more about AbiWord but don't know where to start, this is one way to get some experience!

You can help improve this page! Testing needed!	Some portions of this page could be clarified or elaborated after some basic to intermediate testing of situations, as noted in each situation. Testing is considered an intro/intermediate-level task due to its low to medium difficulty. Individual situations vary.

The Table of Contents, after the Introduction, is also the expert/short version of the instructions - the steps in each section often include screenshots and err on the side of verbosity, since the combination of tools (a Unix-like development style, Subversion version control with two modules, and Microsoft Windows and Visual Studio) might be new or unfamiliar to potential developers coming from either the "pure" Unix or the Windows development sides.

Contents 1 Introduction 1.1 Windows Needed - Virtual Machines Work Great! 1.2 Why MSVC? 1.3 Hard Drive Requirements and Suggestions 1.4 Memory Recommendations 2 Get the Tools 2.1 TortoiseSVN for Version Control 2.2 Microsoft Visual C++ 2008 (Express) 2.3 Optional: MSDN Library (Express) 2.4 NSIS and Plugins (to create installers) 2.5 7-Zip (to open .tar.gz files) 2.6 Perl (to create strings from PO files used for Localization) 3 Create a Source Folder 4 Get the Source - Pick a Method 4.1 Using Version Control 4.1.1 Check Out AbiWord Trunk 4.1.2 Check Out msvc2008 Module Within abiword 4.1.3 Update An Existing Checkout 4.2 From a Source Tarball (Release) - Incomplete 5 Opening and Building 5.1 Go into the msvc2008 folder 5.2 Open the AbiWord.sln Solution File 5.3 Explore the code 5.4 Build and Run AbiWord 6 Report Bugs 7 Submit Changes (creating patches, committing) 7.1 Update your source tree 7.2 Add new files, if applicable 7.3 Find your modified files and clean up your changes 7.4 Double-check the build 7.5 Create the patch or commit your change 7.6 Share your patch

Introduction

MSVC is short for Microsoft Visual C++ 2008, an IDE for C++ development. You can use Microsoft Visual C++ 2008 Express Edition, a free-as-in-beer (but not free-as-in-speech) download, to build AbiWord on Microsoft Windows 2000 Professional*, XP, Server 2003, Vista, Server 2008*, or a Windows 7 pre-release (starred versions known to work by yours truly), or of course any non-Express version of Microsoft Visual Studio 2008 that includes Visual C++ and the ability to build native Win32 applications (AbiWord does not use .NET), such as Microsoft Visual Studio 2008 Professional.

Using MSVC is the quickest, easiest way to get started with AbiWord development on Windows and includes a number of useful tools, such as a debugger, an integrated development environment with editor, and more. There are alternatives, however, see below for details.

Windows Needed - Virtual Machines Work Great!

You do need a valid license for Windows in order to use MSVC and build AbiWord in this way. (It doesn't appear to work in Wine and we can't offer an opinion on the legal legitimacy of attempting to do so without a valid Windows license.) You can, however, run Windows in a virtual machine on Linux or Mac OS X, or even another version of Windows, of course subject to license agreements for your selected Windows OS. You can use the VM copy of Windows to install MSVC and build AbiWord, editing either in the VM or, with the source in a shared folder of some sort, in your preferred Windows, Linux or Mac OS X editor on the host system or a different VM, only using Windows and MSVC to build and run. Some limited free ways (specific sort of free/Free varies - read for yourself to ensure you are complying with the license) to run a licensed copy of Windows in a virtual machine include, in no specific order:

• VMware Server (VMware Server Wikipedia page)
• VMware Player (VMware Player Wikipedia page) using VMware Server or EasyVMX to create the virtual machine configuration initially
• VirtualBox (VirtualBox Wikipedia page)

More virtual machine software: Comparison of platform virtual machines on Wikipedia

For what it's worth: Ryan has only used VMware Player/Server (using the older MinGW system) and the paid VMware Fusion product personally to build AbiWord, though he doubts there's any reasons these other systems would behave differently: pick one according to your needs and your license agreement desires.

Help out: Improve this page by testing out other VM software and updating the section with notes on successful/unsuccessful tests, software versions tested, and date of test.

Why MSVC?

If building using non-Free Microsoft tools gives you moral qualms, you can also cross-compile for Windows using MinGW on a Linux platform (harder), or directly on Windows using MinGW (harder, slower, and more poorly documented).

Help out: Improve this section by adding links to appropriate mailing list posts by Rob, cleardefinition.com (rp) pages for MinGW instructions, and/or create a new page to centralize/canonicalize MinGW instructions.

Hard Drive Requirements and Suggestions

Compiling software takes a lot of room, so (especially if you're creating a virtual machine and have to pick a virtual disk size) make sure you have plenty available. A minimum built source tree includes these components:

• The AbiWord source tree checked out from SVN, with the MSVC files checked out as well
• A single configuration of a completed build of the core AbiWord application in the tree
• The intermediate build files (object files, etc.) created by MSVC

This basic source directory, which doesn't include any plugins or any of the development tools themselves, takes around 700MB. If you want to build the plugins, too, your source tree will expand to about 1GB (compiling the entire solution including plugins). If you build a debug version and a "release" non-debug version, this space requirement will increase dramatically.

In general, you want probably at least 1.5GB free before starting basic AbiWord development (and more is better), just to play it safe in case MSVC requires more space free while building or to give your swap file room to expand. (Nevertheless, AbiWord takes only 20MB installed on its own - all that huge amount of extra space is only needed for development and building.)

If you're creating a virtual machine, choose a large disk size and "sparse" style (sometimes phrased more like "Do not allocate all space initially" or unchecking a checkbox stating the opposite) to set a maximum size disk that will nevertheless start small in actual disk space usage and expand up to the max as needed. You might also consider creating a second disk image exclusively for your source and build files, similarly large and sparse, since it's easier to expand that maximum size with VM software and Windows later on a non-system disk. If the option is provided, at least in VMware software, you want your source files on a disk image configured using the SCSI driver (on VMware Fusion: default for the system drive if installing Server 2008 or I believe when using "Easy Install" to install XP) since it introduces less overhead, and compiling is very disk-intensive.

Memory Recommendations

As always, more RAM memory is better: you want at least 1GB RAM allocated to a Windows 2000 Professional virtual machine, or more if you're using a newer Windows version that isn't so frugal with memory, if you can spare it.

For what it's worth: Ryan hasn't tested to see what the minimum is for a build, but suspects that if you go much below 1GB, especially if 512MB or below, you'll have a fairly sluggish experience. He uses 1GB assigned to a Win2k virtual machine (only tested using MinGW on 2.6.x/pre-new-buildsystem trunk and earlier), and 1.5GB assigned to a Server 2008 virtual machine, and it works well.

Help out: Improve this section by testing out memory requirements and updating this paragraph.

Get the Tools

TortoiseSVN for Version Control

Visit the TortoiseSVN project page to download and install TortoiseSVN, a Subversion version control client for Windows that includes integration into Windows Explorer (the file manager). While it seems like sometimes you don't have to reboot after installing this software, it's really best to do so.

Microsoft Visual C++ 2008 (Express)

Visual C++ 2008 Express Edition is a free (as in beer) development environment and compiler from Microsoft.

• Download and install it. You might also need to install the Platform SDK, potentially.
  • Of course, if you have some other version of Visual Studio 2008 that includes Visual C++ and support for building native Win32 applications, you can use that and skip installing the Express Edition.

Help out: Improve this section by testing to see if you need to separately install the Platform SDK for 2008 like you needed to with earlier Express Editions.

Optional: MSDN Library (Express)

If you'd like to have local reference material on C++ and Win32 programming integrated into the IDE, you can also install the MSDN Library (either the slimmed-down Express edition or the huge full version - both are available for free). You don't need to do this, though: you can access this material online in a web browser as well, at the MSDN Online Library, or, at least for the non-Win32 bits, using your favorite search engine to find other resources.

NSIS and Plugins (to create installers)

• Get the latest Unicode NSIS (we started using Unicode NSIS from release 2.9.4 onwards) and install it with default settings.
• From the Plugins page, download the latest file for the MD5 plugin, the UnTGZ plugin, and the ZipDll plugin.
• Unzip each of those plugins, and place the appropriate files in the Plugins subdirectory under your NSIS install: something like c:\Program FIles\NSIS\Plugins\. You only need to copy the .dll file, and if there are any, the .nsh files should be copied to the Include directory.
• Please make sure that makensis is added to the PATH environment variables.

7-Zip (to open .tar.gz files)

Available at the 7-Zip Download Page (you probably want the "exe, 32-bit, 7-Zip" unless you know otherwise), this is a free, open source zip utility for Windows (like WinZip but free and open source, rather than paid/shareware) that supports Unix-type compressed file formats. You only really need this if you are installing from a downloaded tarball rather than version control, but it's good to have anyway. You might want to associate it (using the preferences dialog in the 7-Zip File Manager) with all filetypes it supports except zip and cab, which are supported natively by Windows, for maximum ease of use. Even if you don't associate it with any filetypes, you can always get to it using right-click in Windows Explorer (the standard file browser).

Perl (to create strings from PO files used for Localization)

Available at the Perl Download Page. This is required for the on the fly strings generation from the PO files used for localization. Please make sure that Perl is added to the PATH environment variables.

Create a Source Folder

• First, decide on a folder to store source code in.
  • In case you ever want to build using the MinGW tools, or build other OSS software that might use those tools, try to create your folder to have no spaces in the path.
  • AbiWord will be in a self-contained subfolder in whichever folder you create, so you can name it generically and put source for other great open source software in it, too!
  • If you're using Windows Vista/2008, it's fine to put it in your profile folder like c:\Users\Yourname\source\, or, on any version of Windows (2000 Pro, XP, or Server 2003 included), c:\src\ is also a fine idea for a source folder.
• Create the blank folder using Windows Explorer. If you're on Vista/2008, you might want to add it to your "favorites" bar.
• Go into that new folder using the file browser (Windows Explorer), then pick a path in the next major section based on your preference.

Get the Source - Pick a Method

Using Version Control

This is the recommended way, and lets you keep up to date with the latest development code. These instructions show how to perform an anonymous checkout (if you don't have a commit account, like if you're just starting developing) of the "trunk" developer mainline - if you want a different development branch, change the SVN checkouts accordingly, and good luck! (If you make the branch yourself, branch abiword-msvc2008 as well)

If you have a commit account, modify the SVN URLs below as seen at Getting the source code - basically, replace http://svn.abisource.com/ with svn+ssh://<username>@svn.abisource.com/svnroot/ in each of the paths. If you're really hardcore, you can make an SSH key and add it to Pageant, but that's beyond the scope of this tutorial. (It's not hard.)

• If you're starting from scratch, make sure to follow both the core checkout and MSVC-specific checkout steps in this section.
• If you already performed a source code checkout according to those steps, skip those checkout steps and follow only the Update an Existing Checkout section.

Check Out AbiWord Trunk

• Right click in your "source" directory, and choose SVN Checkout. (Don't see it? Make sure you installed TortoiseSVN and its Explorer Integration, which is a default option, then rebooted!) Enter the SVN URL

http://svn.abisource.com/abiword/trunk/

• On the checkout directory, add \abiword to the end of the path shown (which should be where you are), so you get a path like c:\Users\Yourname\source\abiword or c:\src\abiword
  • If you wanted, you could add "abiword-trunk" or some other designation instead of just "abiword", if you're like Ryan and build all sorts of different branches. Be careful to modify the directions appropriately, in that case.
• Click OK, leaving all other options at their default setting. Let the checkout complete, this might take a little while.

Check Out msvc2008 Module Within abiword

• Go into the abiword directory you just created with your checkout. You should see a number of folders and files.
• Right-click in a blank area (not on a folder or file!) and choose SVN Checkout again. (If you don't see that menu option, either directly or under the TortoiseSVN item, follow the steps in this subsection in another directory then move the msvc2008 folder into the abiword directory after.)
• This time, you want to enter the SVN URL (again, this is where you change if you have an account or a different branch)

http://svn.abisource.com/abiword-msvc2008/trunk/

• On the checkout directory, it should show your current location, which also should be the path you entered in the previous step. You want this module to be checked out "underneath" the abiword checkout: add \msvc2008 on the end, so it looks like (for example, modify as appropriate): c:\Users\Yourname\source\abiword\msvc2008 or c:\src\abiword\msvc2008
• Click OK, leaving all other options at their default setting. Let the checkout complete - this should also take a while (it's 200MB+).
• Proceed directly to the Opening and Building step - when you come back and want to get new updates to the source, you'll need to only follow the Update an Existing Checkout steps - you do not need to do a fresh checkout again!

Update An Existing Checkout

If you've already checked out the source, but want to update, you'll need to do it in two steps. Make sure that you have closed Visual C++, just to be safe.

1. First, go into your source folder (the parent to the abiword folder), right click on the abiword folder created by your checkout, and choose "SVN Update." Let it complete, this will take a little bit.
2. Then, go into the abiword folder, find that msvc2008 folder, right-click it, and choose "SVN Update." This will update the MSVC project files, and will take a little bit. (You closed MSVC, right?)

If there are conflicts in either step, be sure to resolve them before moving on - that means that someone committed a change to a file you also modified but didn't commit your changes to. When you've resolved a conflict (in a text editor or MSVC), right click that file, choose TortoiseSVN, and choose Resolved. If the upstream change is simply that the developers committed a patch you submitted, you can right-click that file with the conflict, choose TortoiseSVN, and choose Revert. This will eliminate all your changes to that file and replace it with a fresh copy from the server, so if this isn't what you want, resolve the conflict manually!

From a Source Tarball (Release) - Incomplete

Note: Ryan is not sure if release tarballs as of 2.7.2 includes the msvc2008 files somewhere. (You might need to grab the abiword-msvc2008 SVN module at the desired release tag, based on the instructions above, in addition to your main tarball.)

Basic idea of the process: You'll want to put the downloaded tarball in the source folder you created, right click it, and choose 7-Zip, Extract Here if you don't already have a directory named abiword. (If you do, temporarily rename that directory, choose Extract Here on the tarball, then rename your new directory as desired and rename your old directory back to "abiword".)

Help out: Improve this section by investigating to see if msvc2008 files are included in release tarballs, and whether or not it is, creating instructions here to build a specific release getting at least the core source tree from a tarball rather than SVN.

Opening and Building

Go into the msvc2008 folder

Open the AbiWord.sln Solution File

Double-click the AbiWord.sln file. It should open Microsoft Visual C++ 2008 - if it doesn't, open Visual C++ 2008 first and open AbiWord.sln file from within the program.

Explore the code

Most of the actual AbiWord code is in the LibAbiWord project in MSVC, for technical reasons. You can edit it inside the development environment and do anything you'd normally do in MSVC.

Help out: Improve this section by linking to a web resource providing a source overview (Doxygen, wiki, Developer web page, other?)

Build and Run AbiWord

• Click on the Build menu, and choose Build Solution if you want to build AbiWord and all its plugins.
• To just build the core AbiWord, you'll want to build the AbiWord project in the Solution Explorer only. (Click on the AbiWord project, if you didn't set the startup project or have been poking around, then choose Build AbiWord from the menu.)

You can choose a build configuration (Debug or Release) from the toolbar drop-down, and use the "Play" (Start with Debugging) button (or F5) there to start your build of AbiWord in the debugger, which of course works best if you have chosen a debug build. This should work properly. You can also go to the Debug menu and choose Start Without Debugging (or Ctrl-F5) to just run AbiWord, no matter whether you chose a release or debug build.

When you do a build after your initial one, it should only build the files needed to include the changes (whether you made them or they came in from SVN), but you can (and should) clean the solution and build anew if you have a "weird" problem before reporting it as a bug.

If you have the appropriate dependencies installed (NSIS and the few plugins), building the solution in a "Release" configuration will produce the installer, all in a single step.

Report Bugs

If you run across problems in your use of AbiWord or your reading through the code, don't hesitate to file a bug at the AbiWord Bugzilla! You need a free account, which just requires a name and an email address: use a free or "low-importance" email since spambots do browse our Bugzilla from time to time. (You might enjoy using SpamGourmet or Sneakemail for free redirector email addresses: make sure to add a filter to whitelist the Bugzilla software itself!) Learn more about bug reporting on the main AbiWord web site.

Submit Changes (creating patches, committing)

All bugs (whether filed by you or by others) are better with patches! If you've developed a fix or a feature in your checkout of AbiWord, create a patch to attach to the bug suing these steps.

The easiest thing to do to ensure you produce a clean patch file is to only make one logical modification (a single bug, etc.) at a time, so that you can include a patch file created based off of the entire abiword directory, rather than cherrypicking individual files. The instructions will work both ways, though.

Update your source tree

Immediately before starting the patch process, follow the steps in Update an Existing Checkout to make sure your patch applies cleanly to the latest development version. If you're committing directly, Subversion won't let you commit if you haven't updated to the latest revision of the source code. If you're making a patch, it's bad etiquette to provide a patch to a revision that's not the latest, unless for an important reason you have to provide a patch against (the latest!) source code release tarball. Carefully resolve any conflicts from the merge, and if there were conflicts, be observant and especially mindful of the files with resolved conflicts throughout the rest of the process.

Add new files, if applicable

If you've added any new files, right click them, choose TortoiseSVN, and choose Add.

• If you're creating a patch, rather than committing directly, you are able to skip the "Add" step, but it's not recommended in most cases: you'll need to be careful to have the "Show Unversioned Files" options set in all TortoiseSVN dialogs and double-check to ensure your new file is included in the patch.
• If you're adding a binary file and creating a patch, you will need to separately attach the new binary file to the bug report (with a note as to where it should be placed) since it will not be included in the patch - in this special case it might be best to skip the Add step since you won't put this file in the patch anyway.

You might also need to add them to the build environment (project/solution in MSVC, as well as auto* makefiles for other platforms), as appropriate. Adding files to the MSVC project/solution requires an additional patch procedure - keep an eye out for it below.

Find your modified files and clean up your changes

When creating a patch, you'll want to only include those changes that are important - undoing any unimportant changes to whitespace and improving readability (this step) and not including unrelated changes (this step and/or the patch creation step).

• TortoiseSVN adds a "!" emblem on any file in the source that varies from the last update from SVN, as well as all parent folders of those files.
• To get a list of all modified files in your source tree, right-click the abiword directory, choose TortoiseSVN, and choose Check for Modifications to get a list of all files. (Ignore the note about msvc2008 being nested.)

For each modified file (not folder), right click, choose TortoiseSVN, and choose Diff to show a side-by-side view of the changes made. Use this tool to clean up any changes made.

• To revert a single line or multiple lines, such as an unneeded extra blank line, first select by clicking/clicking and dragging (respectively), then right-clicking the selection and choosing "Use other text block".
• To revert a whole block of a diff, right-click it (without first clicking to select) and choose "Use other text block".
• You can undo if you make a mistake, and you need to choose File, Save to save the modifications you've made.
• For more complex cleanups, open the source file in your desired editor (MSVC or another text editor) and make changes: you can save in that editor and choose "Reload" in TortoiseMerge (the diff window) to update the diff display.
• If you find that you don't need any of the changes to a file, you can either
  • leave that file out from your final patch in a later step (if the changes are useful but just not in the context of this patch)
  • or, revert the changes, permanently undoing them (if you don't need the changes ever again, for example, added printf statements or similar in other source files as learning aids). Changes can be reverted most easily with a right-click, TortoiseSVN, Revert.

Double-check the build

For safety's sake, in MSVC, choose Clean Solution, then choose Build Solution to build the application in its entirety, from scratch. Test the resulting application, making sure basic functions (especially any related to your patch) still work and that your patch does what it says it does. Be sure to mention any added bugs or side-effects when sharing the patch: depending on the importance of the patch's change, this will probably mean that modifications will be requested/made before committing the patch to the source tree.

It's important to test again after diff cleanup, even if you tested earlier, because there might have been unintended consequences to the cleanups you made.

If you are committing directly, unless you have a really good reason, do not commit changes that break other things without definite plans to fix those things, and preferably make any such changes in a separate SVN branch rather than the SVN trunk. Remember, if you break the build, you owe symbolic, metaphorical Internet donuts to the community!

Create the patch or commit your change

1. Once you have your source tree cleaned up and final changes tested, it's time to make the patch! Navigate to the parent of the abiword directory (the "source" directory you created long ago). You want to be able to see the parent directory ("abiword" in the most common case) of all the files in the SVN module.
2. Right-click on the abiword directory, choose TortoiseSVN, and choose Create Patch (or right-click, choose SVN Commit if you're committing a change directly using your commit account).
3. You'll be shown a dialog with the names of changed files.
   1. If you created new files without adding them to the repository, in the case of a patch, make sure "Show Unversioned Files" is checked so you can see your extra file.
   2. Make sure the checkbox is checked only next to those (and next to all those) files whose modifications you want to include in your patch/commit.
4. If you are creating a patch, click OK, and save the patch with a "good name".
   1. A "good name" has no spaces (use - or _ instead), short filename, ends in .diff, includes a bug number if relevant, and includes a date (YYYYMMDD format at the beginning of the filename or right after the bug # is a good idea)
   2. Once it has been saved, open the patch in a text editor (notepad, notepad++, etc.) and look through it - does it include all the changes and only the changes that you wanted to include? Is it relatively easy to read and clear? Sometimes the diff algorithm makes some interesting choices, especially if you changed the order of similar code sections, but if there's anything that you can control that would improve the diff, make that change and create a new diff.
5. If you are committing, be sure to enter a good commit message before making the commit. To learn how to write a "good commit message", see the Good Commit Message Guidelines.

Important Note: If you make a change to the MSVC project or solution configuration (a build change, that is, something within the msvc2008 folder, not just edits to a source file from within the MSVC environment), you need to create a patch (potentially a second patch, if you made source changes as well) for the msvc2008 folder specifically instead of/in addition to a patch for the abiword folder - repeat this step except use the msvc2008 directory specifically instead of its parent, the abiword directory. You need to do this because the main AbiWord source and the msvc project files are two separate SVN modules, so they need to be handled separately.

Share your patch

If you committed directly to the source tree,

congratulations, you're almost done! You'll want to:

• update your checkout, just to be safe (and to make sure TortoiseSVN updates its emblems - in theory this step is unnecessary, but in practice it's a harmless and sometimes useful habit.)
• Make sure to mark any bugs fixed by the commit as RESOLVED, noting in the comment the revision number and where it was committed and when it will be in a release version: for example, "Fix committed to the development tree, will be in 2.7.3 development alpha. Needs to be backported to be included in the next stable release, 2.6.9".

If you created a patch,

the best thing to do is attach it to the bug it is associated with.

• Include any comments as to flaws in the patch, unintended side effects, etc, and any details that you think are important that aren't obvious from just looking at the diff.
• If there isn't a bug filed, search again to be sure (there are lots of bugs filed!), then file a new one - yes, even for features (set the severity to "enhancement" and add the keyword "rfe").
• Add the keyword "patch" to the bug once you've attached it, and if someone comments on the patch suggesting changes, etc, follow up and stay involved!

• If for some reason you absolutely have to attach the patch to an email to the developer list, make sure that it is zipped (use 7-zip to "gzip" the diff, if you can, since .zip is not a common format for *nix developers to work with and .gz is much more common and traditional.) If you do not gzip it, your email will look fake and it will be discarded automatically by the spam filter without notifying you or the developers, so beware!