[[TOC()]]
= Installation Guide for Tango used with DMD on Windows =

This page details two ways of installing Tango for DMD on Windows. The first is recommended unless you want to hack Tango itself.

For some, it may make more sense to use DSSS for installation, or use a tool like build/bud or rebuild, the alternatives are suggested at further down on the page.

'''Note:''' These installation instructions assume a default DMD installation and that the archive has been extracted into C:\, creating C:\dmd as the home of the DMD compiler.  The basic goal of this process is to replace Phobos with Tango by placing the Tango object.d and root directories at the head of the DMD include path, and replacing the Phobos libphobos.a with its Tango equivalent of the same name. Note that if your first download of DMD is from the Tango pages, there will be no Phobos to replace.

== Install Binary Bundle ==

 1. [wiki:DmdDownloads#MSWindows Download] Tango, one of the .zip options will suffice
 2. Extract the Tango archive into a new directory named `C:\dmd\import`. If you chose another path, consider avoiding names that contain spaces or parenthesis as these cause problems with some windows command line tools.
 3. Open `C:\dmd\bin\sc.ini` in a text editor.  The contents if tango has not been enabled look like this:
{{{
[Environment]
LIB="%@P%\..\lib";\dm\lib
DFLAGS="-I%@P%\..\src\phobos"
LINKCMD=%@P%\..\..\dm\bin\link.exe
}}}

As all .ini files in Windows, any line beginning with a semicolon ';' will be considered a comment and will therefore be ignored by DMD.  To ensure removal of Tango is as painless as possible, it is a good idea to leave the original lines in the file as comments with the edited line below.

Now, on to the editing:

  3.1. Replace the reference to the Phobos include directory in the DFLAGS line with a reference to the Tango root directory.  This will ensure that the Tango import modules will be used in place of those in Phobos, and replacing the reference reduces the risk of hard to diagnose compile errors. Either a relative or absolute path may be used, as appropriate:
{{{
Relative: "%@P%\..\import"
Absolute: "C:\dmd\import"
}}}
   ''e.g. DFLAGS="-I%@P%\..\import"''

  3.2. Append "-version=Tango" to the DFLAGS line modified above.  This version flag is useful for determining whether Tango is the current default library:
   ''e.g. DFLAGS="-I%@P%\..\import" -version=Tango''
  3.3. Since version 1.023 DMD has a flag to set the name of the runtime library that should be linked in. (It was formerly hardcoded to "phobos.lib" and "libphobos.a")     This basically means, you have to append another switch in order to make Tango the standard runtime in your sc.ini: 
   ''-defaultlib=tango-base-dmd -debuglib=tango-base-dmd''
   Note: ''-debuglib'' is necessary, as of now DMD would fall back to Phobos when compiling with `-g`.

 After making these changes, sc.ini should look like this:
{{{
[Environment]
; LIB="%@P%\..\lib";\dm\lib
LIB="%@P%\..\import\lib;%@P%\..\lib;%@P%\..\..\dm\lib"
; DFLAGS="-I%@P%\..\src\phobos"
DFLAGS="-I%@P%\..\import" -version=Tango -defaultlib=tango-base-dmd -debuglib=tango-base-dmd
LINKCMD=%@P%\..\..\dm\bin\link.exe
}}}

 4. Please note that while ''tango-base-dmd.lib'' and ''tango-win32-dmd.lib'' will be automatically linked, ''tango-user-dmd.lib'' will not. This is to allow for configurations where ''tango-user-dmd.lib'' does not exist (such as when using Bud or Rebuild). To ensure that ''tango-user-dmd.lib'' is linked to an application, either of the following two methods should work.
   * a. Add ''-L+tango-user-dmd.lib'' to the end of the DFLAGS line in ''sc.ini''.
   * b. Add the following to files being compiled.
{{{
pragma(lib, "tango-user-dmd.lib");
}}}
   * c. Include ''tango-user-dmd.lib'' in the list of files to be compiled when using dmd.exe.

== Manual Build and Install ==

Note that these instructions are applicable to the current trunk (post-0.99.8
release) and DMD 1.046 or higher.  They may not apply to older releases of
Tango and/or DMD.

Also note that these instructions assume a pristine environment.  If you wish
to install Tango into an already configured compiler, make sure you follow the
instructions for "Manual Install" in the section on Compiling.

=== Prerequisites ===

You will need both the DigitalMars D and C compilers.  You can download DMD
from the
[http://www.digitalmars.com/d/download.html DigitalMars D download page].
If you are compiling trunk, you will need DMD version 1.045 or higher.
Note that Tango is not currently compatible with D 2.x.

You can download DMC from the same link; specifically, you want `dmc.zip`.

Next, extract the DMD and DMC compilers somewhere.  For our purposes, we will
assume both were extracted to the same directory.  You should have a dm
directory and a dmd directory.  Most paths in this guide are relative to the
directory where you extracted them.

Finally, you will need the Tango source.  You can obtain this from
[wiki:SourceDownloads].  Whether you download a snapshot or check out from
source control, you should ensure the `tango` directory (containing
`README.txt`) is located at `dmd\windows\tango`.

=== Bootstrap Tango ===

This only needs to be done once; once you have compiled Tango at least once,
this step is unnecessary.

Firstly, delete (or rename) the `dmd\src\phobos` directory, then create a new,
empty `dmd\src\phobos` directory.  Copy the `dmd\windows\tango\object.di`
file to `dmd\src\phobos\object.di`.

Once Tango has been installed, your temporary bootstrap `dmd\src\phobos`
directory can be removed.

=== Compile ===

First, ensure that the D compiler you are installing Tango into is the first D
compiler on your system `PATH`.  If you do not have any other copies of DMD
installed on your system, you don't need to worry about this.

You also need to ensure that `dm\bin` is on your `PATH`.

If you are unsure as to what your PATH should look like, the following
batch file configures a minimal PATH for a Windows XP system, and opens a
command prompt:

{{{
SET DMD=\PATH\TO\DMD
SET DMC=\PATH\TO\DMC

SET PATH=%DMD%\windows\bin;%DMC%\bin;%SYSTEMROOT%\system32;%SYSTEMROOT%;%SYSTEMROOT%\system32\Wbem

START CMD
}}}

Note that you will have to change the first two lines to reference the correct
directories.

==== Automated Build and Install ====

'''This section is out of date.'''

Is there an installer at all?

==== Manually Build and Install ====

This is recommended for end users who are installing into an existing
compiler, and for developers who wish to work on Tango itself.

'''This section is out of date.'''

???

Finally, you need to configure DMD to use Tango.  To do this, open the
`dmd\windows\bin\sc.ini` file in a text editor.  One line of this file will
look like this:

{{{
DFLAGS="-I%@P%\..\..\src\phobos"
}}}

You want to delete `"-I%@P%\..\..\src\phobos"` and replace it with
`"-I%@P%\..\tango"`.

You will also want to add the following to the `DFLAGS` setting (note: you do
not need to insert these within quotes; the quotes surround the `-I` flag to
guard against spaces in the path.)

{{{
???
}}}

=== Test ===

Create a file called `happy.d` (in `dmd\windows` is fine) with the
following contents:

{{{
#!d
import tango.io.Stdout;

void main()
{
    Stdout("Don't Worry, Be Happy!").newline;
}
}}}

Compile with the command `dmd happy` and run it to ensure it correctly
outputs "Don't Worry, Be Happy!" and terminates without error.

If you installed manually and chose not to add the `-L+tango-user-dmd.lib`
switch to `DFLAGS`, you will need to compile with
`dmd -L+tango-user-dmd.lib happy`.

=== Clean-Up ===

You can now remove the following superfluous files and directories if you desire:

 * `dmd\freebsd`
 * `dmd\linux`
 * `dmd\man`
 * `dmd\osx`
 * `dmd\src\phobos` (the temporary bootstrap directory you created)

With that, you are done!  You can update to the latest trunk version of Tango
by updating the `dmd\windows\tango` directory, and then following the
instructions for compilation.

== Trouble Shooting ==

[wiki:DMDWin32Problems Problems you may encounter with the DM toolchain]

== Using DSSS ==

[/projects/dsss DSSS] can be used to install Tango, either just the user targeted API, or all of it. All of Tango, including the runtime, can be installed using DSSS' net install feature. Also, if you have installed the runtime, the user API can be installed for use with DSSS by doing

{{{
> dsss build
> dsss install
}}}

in the Tango root directory.

== Using Rebuild / Bud (build) ==

This is similar to using DSSS (rebuild is indeed a part of DSSS), but where you instead of installing libraries, give the build tools the path to Tango, having the objects rebuilt when needed by the built application.

== User Comments ==

[[EmbedReplies(DocComments,WindowsInstall)]]