// To build this file, execute "nant APIDocs"
// After that, you can read the compiled version at doc\output\TortoiseSVNAPI.chm

/**
\page build Build instructions

\section Introduction Introduction
Compiling TortoiseSVN is not very difficult, but it requires several steps
to finish, at least when you do it the first time.

Unlike other big open source projects, once you have built all the libraries
TortoiseSVN depends on, you can use the familiar VisualStudio IDE to build
and debug the binaries. No need to run the build script for every little change.

So don't give up if you read through the next section you will find all the requirements.
You need to perform most steps only once.

\section Requirements Requirements

\subsection Requirements1 First, you need to install the compiler package.

-# You need VS2022 to allow building of the full TortoiseSVN package.
   If you don't have Visual Studio yet, you can download and install
   the community edition for free. When you install Visual Studio, you have
   to select the "MFC", "ATL" packages and the "MSM redistributable" as well.

\subsection Requirements2 Next you need to install some utilities/programs.
- Java runtime                      https://www.java.com
- Python 3(\b 1)                    https://www.python.org/downloads/windows/
                                    or
                                    Windows Store 
- Perl                              http://strawberryperl.com/releases.html
                                    or
                                    https://www.activestate.com/products/perl/
- WiX 3.10(\b 1)                    http://wixtoolset.org/
- NAnt 0.92(\b 1)                   http://nant.sourceforge.net
- NASM 2.16 (Optional \b 2)         https://nasm.us/

(\b 1) Add the paths of the binaries to the PATH environment variable. You may have to
    logoff/logon to make the new environment variables take effect!
    Also make sure to "unblock" the zip file before extracting when you install NAnt.
(\b 2) OpenSSL contains assembler code using optimized hardware instructions to
    increase performance. Add the path of the exe to the PATH environment variable.
    Use the no-asm to avoid the assembler code in OpenSSL if NASM is not installed.


\subsection Requirements3 Finally, you may need to install some fonts.
- Arabic(\b Optional)         http://www7.bev.net/civic/icb/quran/Iqraa_ttf.zip
- Japanese(\b Optional)       msgothic.ttc and msmincho.ttc should be available
                              if you activate support for international fonts in your OS.
- Chinese(\b Optional)        simhei.ttf and simsun.httf should be available
                              if you activate support for international fonts in your OS.

\section Preparations Preparations

Now you're almost ready. Only a few more steps to do:
- create a new folder on your harddisk, e.g. SVN. Make sure you have at least
  4 GB of free space left!!!
- Checkout the TortoiseSVN sources from the Subversion repository into
  SVN\TortoiseSVN. Make sure the path does not have '[' or ']' chars in it!
- Make a copy of the file default.build.user.tmpl in the TortoiseSVN root folder and
  rename that copy to default.build.user. Then adjust the paths as mentioned
  in that file. You may leave it unchanged if you installed / copied everything
  into the suggested default paths.
- Make a copy of the file doc\doc.build.user.tmpl and rename that copy to
  doc\doc.build.user. Then adjust the paths in that file according to your
  setup. You need to edit this file if your installed version of Tortoise has a different
  working-copy database version than the tool expects.
- Unzip (if necessary) and copy the font files into %WINDIR%\Fonts.
  You will need them only if you are building the respective language packs.
- run 'nant init' to fetch and unzip the required tools. Note: you need to call vcvars32.bat first.

\section digitally signing the binaries and installers

The build scripts will automatically sign all necessary files digitally using a specified
certificate. A digitally signed installer for example won't trigger a warning when the user
tries to install it.

To set up the signing process, you have to create a text file named "signinfo.txt" in the root directory.
That file must contain the command line arguments that you would pass to the signtool.exe command if
you would sign the files manually. So for example, the file content of signinfo.txt could look like this:
\verbatim
/I "Code Signing CA SHA2" /fd SHA256 /a /tr "http://timestamp.sectigo.com/" /d "TortoiseSVN" /du "https://tortoisesvn.net" /q
\endverbatim
make sure you pass "/fd SHA256"!
You can omit the timestamp server (the /tr param) if you don't need it.

For Windows 11 TortoiseSVN also uses a sparse package to get a Windows identity. To get that, another file
named "signpublisher.txt" must be created. This file must contain the publisher string of your signing certificate.
The one currently used to sign the official TortoiseSVN binaries is
\verbatim
E=tortoisesvn@gmail.com, CN="Open Source Developer, Stefan KUENG", O=Open Source Developer, L=Altstätten, C=CH
\endverbatim
so the signpublisher.txt file contains exactly that string. Note the """ in the string: the string must be escaped to be used in an xml file.

If you've created these two files with your certificate info, then the build scripts will do the rest and
sign all necessary files.

If you don't have an official digital certificate and want to use a self-signed
certificate, please note that such a certificate also has to be created a certain
way. Here's how to create a self-signed certificate that will work:
https://docs.microsoft.com/en-us/windows/win32/appxpkg/how-to-create-a-package-signing-certificate

\section build32 Building 32 bit packages

  Hint: before you can start building TortoiseSVN, you need to call the vcvars32.bat
  file which is located in C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build.

  Now, if you got some time left you can run the build script to compile
  TortoiseSVN. Grab a cup of coffee, depending on how fast your computer is!
  TortoiseSVN build can take advantage of multi-core machines.

  Note: if you set the Visual Studio tools for win32, you can not build the
  64-bit version of TortoiseSVN. Trying to use the 'x64' nant target will
  result in a build error.
  To build the 64-bit version, you have to call the 64-bit Visual Studio tools.
  And with the 64-bit tools, you can not build the 32-bit version of TortoiseSVN.
  Basically: you need to set up the corresponding Visual Studio tools for the build.

\verbatim
  > nant
\endverbatim
  will show you some help about the targets you can use

\verbatim
  > nant setup
\endverbatim
  will compile everything, including docs and language packs and create the msi installer

  If you encounter any build errors, you can run nant again like this:
\verbatim
  > nant setup -l:buildlog.txt
\endverbatim
  which will create a build log file which you can use to analyze where
  exactly the build failed.

  If you need to build only the Subversion libraries:
\verbatim
  > nant Subversion
\endverbatim

\section build64 Building 64 bit packages

  To build native packages on your 64 bit Windows, just open
  "Visual Studio 2022" -> "Visual Studio Tools" ->
  "Developer Command Prompt for VS 2022", change to the
  TortoiseSVN source directory and run
  
  Note that to build the x64 msi file, you also have to build the
  win32 version of TortoiseSVN first since the x64 msi includes
  the win32 version of the shell extension.

\verbatim
  > nant x64 setup
\endverbatim

  After the script finished, the packages can be found in bin.

\section buildarm64 Building ARM 64 bit packages on win64 (cross-compile)

  First, we build some 32-bit SVN utilities you will need later
  during the build process. Follow the instructions under
  "Building 32 bit packages".
  
  Start a new instance of the Command Prompt and call the vcvarsamd64_arm64.bat
  file which is located in C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build.

  Now run

\verbatim
  > nant ARM64 cross setup
\endverbatim

  After the script finished, the packages can be found in bin.

\section clean Cleaning the build directories

  To clean the files you just built, open a command prompt as explained
  above, change to the TortoiseSVN source directory and run

\verbatim
  > nant clean
\endverbatim

  You will find that Language\Tortoise.pot gets deleted when running the 'clean' target,
  which is normal behavior. This generated file is present in the repository so
  the translators don't need to execute the entire build if they only wish to
  update documentation.

\section buildhelp Learning the current build options

  Many other settings can be used. You can see a description of the available nant targets
  by running

\verbatim
  > nant help
\endverbatim

*/