# VirtualDub source code - build notes

This file automatically displays the first time you attempt to build VirtualDub, in order to warn you of possible pitfalls. It won't auto-display. Look in the `Docs` project for this file and other documentation.

## Quickstart

- Set build target to `Helpfile - Win32 Debug` and build. This will automatically build the HTML compiler, Lina, and the help archive.
- Set build target to `VirtualDub - Win32 Debug` and build. This will compile the build tools, support libraries, then the final application.

## Build requirements

You need the following tools to build VirtualDub out of the box:

- Microsoft Windows NT 4.0, 2000, or XP. You can build under 95/98/ME, but you will need to modify the build process.
- Microsoft Visual C++ 6.0 or Microsoft Visual Studio .NET (2002). Intel C/C++ 6.0/7.0 is optional.
- Info-ZIP for Win32 (`zip.exe`).

## General notes

Version 1.5.0 has a significantly different build setup than the 1.4.x series. As of 1.5.0, mapconv and verinc are included with the main source archive, and NekoAmp 2.0 (Priss) and Sylia are statically linked into the application. Building VirtualDub.exe should be as simple as selecting VirtualDub as the active project and starting a build. Special project directories:

> lib/<build>/ | static libraries
> h/ | interface-level include files
> obj/<build>/ | object files
> out/<build>/ | executables and link output

Make sure you're not releasing debug builds!

## Stylistic changes from V1.4

V1.5 contains a number of stylistic changes from V1.4 that may be annoying to those attempting a reintegration with an earlier fork. Among the changes:

- NekoAmp has been rewritten and no longer contains any third party code -- in particular, it no longer contains GPL'ed code from the FreeAmp project. It has also been renamed to Priss (anime fans will know why -- the benefit of hobbies is that frivolousness is permitted even when it annoys everyone else).
- The system library contains core classes and functions that were previously in the main project. The primary components of system to be aware of:
  - `<vd2/system/vdtypes.h>` is the global include.
  - `<vd2/system/File64.h>` provides unbuffered file I/O.
  - `<vd2/system/thread.h>` provides threading services.
  - `<vd2/system/filesys.h>` does basic path manipulation.
  - `<vd2/system/text.h>` transforms strings between ANSI and Unicode.
  - `<vd2/system/VDString.h>` is the VirtualDub string class.
- Use of Microsoft Windows specific types in app code (DWORD, LONG, etc.) is deprecated in favor of sized types (uint8, sint32), and int/unsigned for known small numbers.
- A few code modules are now Unicode-aware. For instance, VDFile can be fed a wide filename (const wchar_t *) and will use CreateFileW() under Windows NT.
- The Visual C++ _RPTx() macros have been replaced by the VDDEBUG() macro, which supports printf semantics. A VDDEBUG2() macro is available for release-mode debugging, and VDASSERT() is available for compile-time asserts.
- The C++ language is extended with two giant-size hacks:
  - The `vdsynchronized` macro implements Java-style block scoping for lock acquisition and release:

    >     vdsynchronized(mFooLock) {
    >         DoStuff(mFoo);
    >     }

  - `vdprotected` implements a processing context to be reported on a crash:

    >     vdprotected("doing foo") {
    >         for(int i=0; i<10; ++i)
    >            vdprotected("in foo iteration %d", int, i)
    >                if (i == 5)
    >                    *(char *)0 = 0;
    >     }

    Current scopes are indicated on a crash:

    >     An out-of-bounds memory access (access violation) occurred in module 'VirtualDub'...
    >     ...while in foo iteration 5 (Init.cpp:111)...
    >     ...while deliberately trying to crash (Init.cpp:132).

  Both constructs are unbrace-friendly (single controlled statement without braces works fine) and exception-handling friendly (finalization still occurs if an exception is thrown).

## Tools

Four build tools are included in the workspace:

> disasm
>   Compiles and checks the IA-32 architecture disassembly data module. This is not built or run by default, since the disassembly module rarely changes.
> mapconv
>   Parses the map output from the Microsoft linker and produces an address-to-function symbol lookup table. This is built and run automatically as part of the build process and combines the `virtualdub.map` and `ia32.vdi` to produce `virtualdub.vdi`.
> verinc
>   Performs build number incrementing. Build information is held in `version2.bin` and reflected into `version.bin` for mapconv compatibility. Build counts are tracked by hostname, so development can occur on multiple machines and the source code control system in use can merge the `version2.bin` files to maintain the cumulative build count.
> Lina
>   A HTML compiler required to build the help file.

## Building under Microsoft Visual C++ 6.0

In order to compile VirtualDub with Visual C++ 6.0, you must have the following updates from Microsoft:

- Visual C++ 6.0 Processor Pack
- Visual C++ 6.0 Service Pack 5

You will also need updated include files from the Platform SDK. You do not need the import libraries as VirtualDub dynamically links to functions not available in the retail version of Windows 95.

- Platform SDK website
Important Use the Download link on the toolbar to install only the Build Environment from the Core SDK. If you click Install this SDK! from the Core SDK link, you will forced to install all 100MB+ of the Core SDK instead of 30MB.
- Entire Platform SDK by regular HTTP. This includes a lot more than you need, but this way you can archive it and not have to put up with the stupid online downloader.

You may want to stash your C2.DLL from SP5 before installing the Processor Pack, as you can swap it out with the C2.DLL from the Processor Pack to work around any back-end code generation problems you may have on other projects. In case you forgot to do so, the various versions of C2.DLL are hidden in the self-extracting cabinet files of the Service Pack 5 install.

MASM 6.15 or later (ML.EXE) is required to compile the assembly modules. You should already have this from the Processor Pack.

## Building under Microsoft Visual Studio .NET (2002)

Visual Studio .NET automatically installs MASM 7.0, so you do not need to manually install an assembler.

Projects imported from Visual C++ 6.0 have Buffer Security Checks (/GS) enabled by default. Disable this flag, as it will hinder performance and may destabilize the app.

Do not link any VirtualDub DLLs with the Multithreaded DLL (/MD) code generation setting in VC7. The reason is that Visual Studio .NET now uses its own MSVCR70.DLL instead of the operating system MSVCRT.DLL, thus negating the advantage of doing a DLL CRT link. Use the static multithreaded C runtime library (/MT) instead.

Don't expect significant performance increases by using .NET -- VirtualDub has a fairly simple class hierarchy, leaving fewer opportunities for global inlining optimization, and virtually the only difference between the SP5+PP code generator and the VC7 code generator is loop unrolling, which is seldom effective in this case.

Although Visual Studio .NET (2002) will work for compiling VirtualDub, the official compiler target is still Visual C++ 6.0 SP5+PP; this will not change until the VS.NET IDE sucks less.*

*with apologies to J.Carmack

## Notes for building under Intel C/C++ Compiler 6.0

The P4 build of version 1.5.0 is built with Intel C/C++ 6.0 and Visual C++ 6.0 SP5+PP; Visual Studio .NET 2002 can be used as well provided that the projects and workspace are suitably converted as described above. To build the P4 release, simply choose Win32 Release ICL as the build target. The frameserver libraries are not built under this configuration, so you will need to build them from the regular Win32 Release target; also, a few of the framework libraries -- Dita, Sylia, and system -- are still built under Visual C++. The reason is that Intel C++'s /O1 (optimize for size) code generation produces code that is larger than VC6's /O1 and slower than VC6's /O2 (optimize for speed). Note that even with these libraries built VC6, the ICL executable is still ~30% bigger.

As of this writing, mpeg_idct.cpp does not build properly under the Intel compiler, and will bomb with an intentional #error if you attempt to do so. The reason is a couple of bugs in the compiler's inline assembly support. The Visual Studio .NET project included in this archive already has the Intel compiler disabled for that module.

Building VirtualDub under the Intel compiler will result in an executable that runs only under Intel Pentium 4 processors and other processors that support SSE2 -- the initialization code will display a message box and abort otherwise.

If you get link errors with _pow when compiling with Intel C/C++, find out which module is pulling in the Visual C++ pow() function, and switch it to the Intel compiler. NekoAmp 2.0 (Priss), in particular, needs to be compiled ICL.

## Final notes

Good luck!

    -- Avery Lee <phaeron@virtualdub.org>