doc/compile-for-windows.md

   1 # Notes On Compiling SQLite On Windows 11
   2
   3 Here are step-by-step instructions on how to build SQLite from
   4 canonical source on a new Windows 11 PC, as of 2023-11-01:
   5
   6   1.  Install Microsoft Visual Studio. The free "community edition"
   7       will work fine.  Do a standard install for C++ development.
   8       SQLite only needs the
   9       "cl" compiler and the "nmake" build tool.
  10
  11   2.  Under the "Start" menu, find "All Apps" then go to "Visual Studio 20XX"
  12       and find "x64 Native Tools Command Prompt for VS 20XX".  Pin that
  13       application to your task bar, as you will use it a lot.  Bring up
  14       an instance of this command prompt and do all of the subsequent steps
  15       in that "x64 Native Tools" command prompt.  (Or use "x86" if you want
  16       a 32-bit build.)  The subsequent steps will not work in a vanilla
  17       DOS prompt.  Nor will they work in PowerShell.
  18
  19   3.  Install TCL development libraries.  This note assumes that you will
  20       install the TCL development libraries in the "`c:\Tcl`" directory.
  21       Make adjustments
  22       if you want TCL installed somewhere else.  SQLite needs both the
  23       "tclsh.exe" command-line tool as part of the build process, and
  24       the "tcl86.lib" library in order to run tests.  You will need
  25       TCL version 8.6 or later.
  26       <ol type="a">
  27       <li>Get the TCL source archive, perhaps from
  28       [https://www.tcl.tk/software/tcltk/download.html](https://www.tcl.tk/software/tcltk/download.html).
  29       <li>Untar or unzip the source archive.  CD into the "win/" subfolder
  30           of the source tree.
  31       <li>Run: `nmake /f makefile.vc release`
  32       <li>Run: `nmake /f makefile.vc INSTALLDIR=c:\Tcl install`
  33       <li>CD to `c:\Tcl\lib`.  In that subfolder make a copy of the
  34           "`tcl86t.lib`" file to the alternative name "`tcl86.lib`"
  35           (omitting the second 't').  Leave the copy in the same directory
  36           as the original.
  37       <li>CD to `c:\Tcl\bin`.  Make a copy of the "`tclsh86t.exe`"
  38           file into "`tclsh.exe`" (without the "86t") in the same directory.
  39       <li>Add `c:\Tcl\bin` to your %PATH%.  To do this, go to Settings
  40           and search for "path".  Select "edit environment variables for
  41           your account" and modify your default PATH accordingly.
  42           You will need to close and reopen your command prompts after
  43           making this change.
  44       </ol>
  45
  46   4.  Download the SQLite source tree and unpack it. CD into the
  47       toplevel directory of the source tree.
  48
  49   5.  Set the TCLDIR environment variable to point to your TCL installation.
  50       Like this:
  51       <ul>
  52       <li> `set TCLDIR=c:\Tcl`
  53       </ul>
  54
  55   6.  Run the "`Makefile.msc`" makefile with an appropriate target.
  56       Examples:
  57       <ul>
  58       <li>  `nmake /f makefile.msc`
  59       <li>  `nmake /f makefile.msc sqlite3.c`
  60       <li>  `nmake /f makefile.msc devtest`
  61       <li>  `nmake /f makefile.msc releasetest`
  62       </ul>
  63
  64 ## 32-bit Builds
  65
  66 Doing a 32-bit build is just like doing a 64-bit build with the
  67 following minor changes:
  68
  69   1.  Use the "x86 Native Tools Command Prompt" instead of
  70       "x64 Native Tools Command Prompt".  "**x86**" instead of "**x64**".
  71
  72   2.  Use a different installation directory for TCL.
  73       The recommended directory is `c:\tcl32`.  Thus you end up
  74       with two TCL builds:
  75       <ul>
  76       <li> `c:\tcl` &larr;  64-bit (the default)
  77       <li> `c:\tcl32` &larr;  32-bit
  78       </ul>
  79
  80   3.  Ensure that `c:\tcl32\bin` comes before `c:\tcl\bin` on
  81       your PATH environment variable.  You can achieve this using
  82       a command like:
  83       <ul>
  84       <li>  `set PATH=c:\tcl32\bin;%PATH%`
  85       </ul>
  86
  87 ## Building a DLL
  88
  89 The command the developers use for building the deliverable DLL on the
  90 [download page](https://sqlite.org/download.html) is as follows:
  91
  92 > ~~~~
  93 nmake /f Makefile.msc sqlite3.dll USE_NATIVE_LIBPATHS=1 "OPTS=-DSQLITE_ENABLE_FTS3=1 -DSQLITE_ENABLE_FTS4=1 -DSQLITE_ENABLE_FTS5=1 -DSQLITE_ENABLE_RTREE=1 -DSQLITE_ENABLE_JSON1=1 -DSQLITE_ENABLE_GEOPOLY=1 -DSQLITE_ENABLE_SESSION=1 -DSQLITE_ENABLE_PREUPDATE_HOOK=1 -DSQLITE_ENABLE_SERIALIZE=1 -DSQLITE_ENABLE_MATH_FUNCTIONS=1"
  94 ~~~~
  95
  96 That command generates both the sqlite3.dll and sqlite3.def files.  The same
  97 command works for both 32-bit and 64-bit builds.
  98
  99 ## Statically Linking The TCL Library
 100
 101 Some utility programs associated with SQLite need to be linked
 102 with TCL in order to function.  The [sqlite3_analyzer.exe program](https://sqlite.org/sqlanalyze.html)
 103 is an example.  You can build as described above, and then
 104 enter:
 105
 106 > ~~~~
 107 nmake /f Makefile.msc sqlite3_analyzer.exe
 108 ~~~~
 109
 110 And you will end up with a working executable.  However, that executable
 111 will depend on having the "tcl86.dll" library somewhere on your %PATH%.
 112 Use the following steps to build an executable that has the TCL library
 113 statically linked so that it does not depend on separate DLL:
 114
 115   1.  Use the appropriate "Command Prompt" window - either x86 or
 116       x64, depending on whether you want a 32-bit or 64-bit executable.
 117
 118   2.  Untar the TCL source tarball into a fresh directory.  CD into
 119       the "win/" subfolder.
 120
 121   3.  Run: `nmake /f makefile.vc OPTS=nothreads,static shell`
 122
 123
 124   4.  CD into the "Release*" subfolder that is created (note the
 125       wildcard - the full name of the directory might vary).  There
 126       you will find the "tcl86s.lib" file.  Copy this file into the
 127       same directory that you put the "tcl86.lib" on your initial
 128       installation.  (In this document, that directory is
 129       "`C:\Tcl32\lib`" for 32-bit builds and
 130       "`C:\Tcl\lib`" for 64-bit builds.)
 131
 132   5.  CD into your SQLite source code directory and build the desired
 133       utility program, but add the following extra arguments to the
 134       nmake command line:
 135       <blockquote><pre>
 136       CCOPTS="-DSTATIC_BUILD" LIBTCL="tcl86s.lib netapi32.lib user32.lib"
 137       </pre></blockquote>
 138       <p>So, for example, to build a statically linked version of
 139       sqlite3_analyzer.exe, you might type:
 140       <blockquote><pre>
 141       nmake /f Makefile.msc CCOPTS="-DSTATIC_BUILD" LIBTCL="tcl86s.lib netapi32.lib user32.lib" sqlite3_analyzer.exe
 142       </pre></blockquote>
 143
 144   6.  After your executable is built, you can verify that it does not
 145       depend on the TCL DLL by running:
 146       <blockquote><pre>
 147       dumpbin /dependents sqlite3_analyzer.exe
 148       </pre></blockquote>