From AbiWiki

Revision as of 19:26, 5 June 2009

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.

Introduction

MSVC is short for Microsoft Visual C++ 2008, an IDE for C++ development. You can use Microsoft Visual C++ 2008 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: [User:rp 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.

Other Requirements

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. The AbiWord source tree checked out from SVN, with the MSVC files checked out as well, a completed build of the core AbiWord application in the tree, and the intermediate build files (object files, etc.) created by MSVC, takes around 700MB, and in general, you want probably at least 1.5GB free before starting AbiWord development, just to play it safe in case MSVC requires more space free while building or to give your swap file room to expand.

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.

As always, more RAM memory is better: you want at least 1GB 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. [User:rp 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). It will suggest you reboot after installing - while the Explorer integration seems to work right away on Windows 2000, it does appear to actually need that reboot on Vista/2008.

Help out: Improve this page by figuring out this reboot thing, or removing any reference to not rebooting and just mandate a reboot.

Microsoft Visual C++ 2008 (Express)

This is a free (as in beer) development environment and compiler from Microsoft: Visual C++ 2008 Express Edition Download and install it. You might also need to install the Platform SDK, I'm not sure (I used the Professional Edition, not the Express Edition - could someone verify this?)

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

Available at the 7-Zip Download Page (you probably want the 32-bit exe installer unless you know otherwise), this is a free, open source zip utility for Windows (like WinZip but free) 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 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 those filetypes, you can always get to it using right-click in Windows Explorer (the standard file browser).

Create a Source Folder

First, make a folder to store source code in: 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),

c:\src\

is also a fine idea for a source folder. In case you ever want to build using the MinGW tools, try to keep it in a folder with 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!

Go into that 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 have an account, or if you want a different development branch, change the SVN checkouts accordingly, and you're on your own (especially if you pick a different branch).

Help out: Improve this section by adding instructions for installing necessary Pageant/Putty SSH pieces and SSH keys, and performing checkouts (and commits) using a "commit" (blueant) account.

If you're starting from scratch, make sure to follow both of the Check Out steps in this section, skipping the update section. If you already did a checkout according to these steps, skip those steps and follow only the update section.

Check Out AbiWord Trunk (Fresh Checkout - First Time Only)

Right click, 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 path

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

(This is where you'd change the path if you have a commit account, or if you want to use another branch, though the MSVC stuff only works with the trunk branch as of June 2009.)

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, if you're like [User:Rp] 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 Solution Files

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. This time, you want to enter the SVN path (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. Add "\msvc2008" on the end, so it looks like

c:\Users\Yourname\source\abiword\msvc2008

or

c:\src\abiword\msvc2008

or the equivalent for where ever you decided to put your source. You want this module to be checked out "underneath" the abiword checkout.

Click OK, leaving all other options at their default setting. Let the checkout complete - this one should be reasonably quick, but not instantaneous.

Proceed 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" section of these instructions - you do not need to do a fresh checkout again!

Or, 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. 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.

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

[User:rp Ryan] is ntot 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.)

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

Remember, it's in your source\abiword\ folder, so you'll need to navigate to something like

c:\Users\Yourname\source\abiword\msvc2008

or

c:\src\abiword\msvc2008

if you've used the suggested paths so far.

Open the Solution File

Double-click the AbiWord.sln file. It should open Microsoft Visual C++ 2008 - if it doesn't (because you have another version of Visual Studio installed, or some other reason), open MSVC, choose File, Open, and navigate to the AbiWord.sln file from there.

Optional (and one time only if you save the solution): Set the Startup Project

As of 5 June 2009, the startup project in the solution is the OpenDocument plugin, for some reason. (If that doesn't mean anything to you, just follow these steps the first time if you want to only build AbiWord and no import/export or tools plugins, and don't know your way around MSVC well.) This will probably end up getting fixed sooner or later, in which case following these steps and saving will have produced a conflict: in that case, don't be afraid to revert the solution file or project files in the msvc2008 folder, since that's not actually the source code, just configuration for MSVC. If you always want to build AbiWord and its plugins (the entire solution, not just the core AbiWord/libabiword project) or are comfortable just building a single project in the solution (click on it first and read the menu item to verify before building), you can skip these steps.

Right-click on AbiWord in the left "Solution Explorer" pane, and choose "Set as StartUp Project."

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.

Report Bugs and Submit Patches

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!)

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, here's how to create a patch to attach to the bug:

'Help out: Improve this section by finishing it, preferably with screenshots.