README.md
1# ESP-IDF Tools Installer for Windows
2
3This directory contains source files required to build the tools installer for Windows.
4
5The installer is built using [Inno Setup](http://www.jrsoftware.org/isinfo.php). At the time of writing, the installer can be built with Inno Setup version 6.0.2.
6
7The main source file of the installer is `idf_tools_setup.iss`. PascalScript code is split into multiple `*.iss.inc` files.
8
9Some functionality of the installer depends on additional programs:
10
11* [Inno Download Plugin](https://bitbucket.org/mitrich_k/inno-download-plugin) — used to download additional files during the installation.
12
13* [7-zip](https://www.7-zip.org) — used to extract downloaded IDF archives.
14
15* [cmdlinerunner](cmdlinerunner/cmdlinerunner.c) — a helper DLL used to run external command-line programs from the installer, capture live console output, and get the exit code.
16
17## Installation of dependencies via Chocolatey
18
19Run with Administrator privileges:
20
21```
22choco install inno-download-plugin
23```
24
25## Building the installer
26
27### In Docker
28
29This uses `wine-innosetup` Docker image and `build_installer.sh` script. This is how the installer is built in CI.
30
31```
32docker run --rm -v $IDF_PATH:/idf -w /idf/tools/windows/tool_setup -it $CI_DOCKER_REGISTRY/wine-innosetup:1 /bin/bash build_installer.sh
33```
34
35### Manually, step by step
36
37* Build cmdlinerunner DLL.
38 - On Linux/Mac, install mingw-w64 toolchain (`i686-w64-mingw32-gcc`). Then build the DLL using CMake:
39 ```
40 mkdir -p cmdlinerunner/build
41 cd cmdlinerunner/build
42 cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-i686-w64-mingw32.cmake -DCMAKE_BUILD_TYPE=Release ..
43 cmake --build .
44 ```
45 This will produce `cmdlinerunner.dll` in the build directory.
46 - On Windows, it is possible to build using Visual Studio, with CMake support installed. By default, VS produces build artifacts in some hard to find directory. You can adjust this in CmakeSettings.json file generated by VS.
47
48* Download 7zip.exe [("standalone console version")](https://www.7-zip.org/download.html) and put it into `unzip` directory (to get `unzip/7za.exe`).
49
50* Download [idf_versions.txt](https://dl.espressif.com/dl/esp-idf/idf_versions.txt) and place it into the current directory. The installer will use it as a fallback, if it can not download idf_versions.txt at run time.
51
52* Create the `dist` directory and populate it with the tools which should be bundled with the installer. At the moment the easiest way to obtain it is to use `install.sh`/`install.bat` in IDF, and then copy the contents of `$HOME/.espressif/dist` directory. If the directory is empty, the installer should still work, and the tools will be downloaded during the installation.
53
54* Build the installer using Inno Setup Compiler: `ISCC.exe idf_tools_setup.iss`.
55
56## Signing the installer
57
58* Obtain the signing key (e.g `key.pem`) and the certificate chain (e.g. `certchain.pem`). Set the environment variables to point to these files:
59 - `export KEYFILE=key.pem`
60 - `export CERTCHAIN=certchain.pem`
61
62* Run `sign_installer.sh` script. This will ask for the `key.pem` password, and produce the signed installer in the Output directory. If you plan to run the script multiple times, you may also set `KEYPASSWORD` environment variable to the `key.pem` password, to avoid the prompt.
63
64## Development and testing of the installer
65
66Development and testing of the installer can be simplified by using command line parameters which can be passed to the installer.
67
68Select Run - Parameters in Inno Setup and add parameters.
69
70Example of parameters:
71
72```
73/SKIPSYSTEMCHECK=yes /IDFVERSIONSURL=http://localhost:8000/idf_versions.txt /GITRESET=no /GITREPO=C:/projects/esp-idf /GITRECURSIVE=no
74```
75
76These combinations of parameters will result:
77* ``SKIPSYSTEMCHECK=yes`` - The screen with System Check will be skipped.
78* ``IDFVERSIONURL`` - idf_versions.txt will be downloaded from localhost:8000
79 - it's possible to add branch name into idf_versions.txt, e.g. feature/win_inst
80* ``GITRESET=no`` - Git repository won't be reset after clone, it can save time and add custom changes in case of the zip archive with repository
81* ``GITREPO`` - The version will be cloned from the specific location, e.g. from a local directory
82* ``GITRECURSIVE=no`` - The clone of the repo won't contain modules, it speeds up the cloning process. Use when modules are not necessary.
83
84Documentation of parameters is available in api-guides/tools/idf-windows-installer.rst
85
86### Testing installation in Docker with Windows containers
87
88The testing script is stored in docker-compose.yml. The test perform full silent installation and executes build of get-started example.
89
90Commands for testing multiple versions:
91
92```
93$env:IDF_VERSION="v4.1"; docker-compose.exe run idf-setup-test
94$env:IDF_VERSION="v4.0.2"; docker-compose.exe run idf-setup-test
95$env:IDF_VERSION="v3.3.4"; docker-compose.exe run idf-setup-test
96$env:IDF_VERSION="release/v4.2"; docker-compose.exe run idf-setup-test
97$env:IDF_VERSION="release/v4.1"; docker-compose.exe run idf-setup-test
98$env:IDF_VERSION="release/v4.0"; docker-compose.exe run idf-setup-test
99$env:IDF_VERSION="release/v3.3"; docker-compose.exe run idf-setup-test
100$env:IDF_VERSION="master"; docker-compose.exe run idf-setup-test
101```
102
103The installation log is not displayed immediately on the screen. It's stored in the file and it's displayed when the installation finishes. The glitch of Inno Setup is that in case of failed installation it won't terminate and it keeps hanging.
104
105Recommendation: Use Visual Studio Code with Docker plugin to work with container.
106The log file is then accessible under Docker - Containers - Container - Files - Temp - install.txt - right click - Open.
107
