1# Compiling from sources
2
3## Microsoft Windows (10, 8.1)
4
5### Common Requirements
6
7On Windows users should ensure that the following software is installed:
8
9- `git` (_optional, but recommended_)
10- `cmake` (3.17.0 or later)
11- `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0
12
13### Installation
14
151. Install `git` from <https://git-scm.com/download/win>
162. Install `cmake` from <https://cmake.org/download><br />
17   Ensure that you add cmake to the $PATH system variable when following the instructions by the setup assistant.
183. Install
19
20- _EITHER_: **MinGW-w64** from <https://sourceforge.net/projects/mingw-w64> (mingw-w64-install.exe)<br />
21- _OR_: **MSVC toolchain** from Visual Studio Build Tools 2019
22
234. Create a new destination folder at a place of your choice
245. Open the command-line (cmd.exe) and execute `cd C:\$Path-to-your-destination-folder$\`
256. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`from the command-line (cmd.exe)<br />
26   or download the stlink zip-sourcefolder from the Release page on GitHub
27
28#### MSVC toolchain - minimal installation
29
30Visual Studio IDE is not necessary, only Windows SDK & build tools are required (~3,3GB).
31
321. Open <https://visualstudio.microsoft.com/downloads/>
332. Navigate through menus as follows (might change overtime)
34
35   `All downloads > Tools for Visual Studio 2019 > Build Tools for Visual Studio 2019 > Download`
36
373. Start downloaded executable. After Visual Studio Installer bootstraps and main window pops up, open `Individual Components` tab, and pick
38
39- latest build tools (eg. `MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)`)
40- latest Windows SDK (eg. `Windows 10 SDK (10.0.18362.0)`)
41
424. After installation finishes, you can press `Launch` button in Visual Studio Installer's main menu.
43   - Thus you can open `Developer Command Prompt for VS 2019`. It is `cmd.exe` instance with adjusted PATHs including eg. `msbuild`.
44   - Alternatively, you can use `Developer Powershell for VS 2019` which is the same thing for `powershell.exe`. Both are available from Start menu.
45   - Another option is to add `msbuild` to PATH manually. Its location should be `C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin`. Then, it should be available from any `powershell.exe` or `cmd.exe` session.
46
47### Building
48
49#### MinGW-w64
50
511. Use the command-line to move to the `scripts` directory within the source-folder: `cd stlink\scripts\`
522. Execute `./mingw64-build.bat`
53
54NOTE:<br />
55Per default the build script (currently) uses `C:\Program Files\mingw-w64\x86_64-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw64\bin`.<br />
56When installing different toolchains make sure to update the path in the `mingw64-build.bat`.<br />
57This can be achieved by opening the .bat file with a common text editor.
58
59#### MSVC toolchain
60
611. In a command prompt, change the directory to the folder where the stlink files were cloned (or unzipped) to.
622. Make sure the build folder exists (`mkdir build` if not).
633. From the build folder, run cmake (`cd build; cmake ..`).
64
65This will create a solution file `stlink.sln` in the build folder.
66Now, you can build whole `stlink` suite using following command:
67
68```
69msbuild /m /p:Configuration=Release stlink.sln
70```
71
72Options:
73
74- `/m` - compilation runs in parallel utilizing multiple cores
75- `/p:Configuration=Release` - generates _Release_, optimized build.
76
77Directory `<project_root>\build\Release` contains final executables.
78(`st-util.exe` is located in `<project_root>\build\src\gdbserver\Release`).
79
80**NOTE 1:**
81
82Executables link against libusb.dll library. It has to be placed in the same directory as binaries or in PATH.
83It can be copied from: `<project_root>\build\3rdparty\libusb-{version}\MS{arch}\dll\libusb-1.0.dll`.
84
85**NOTE 2:**
86
87[ST-LINK drivers](https://www.st.com/en/development-tools/stsw-link009.html) are required for `stlink` to work.
88
89## Linux
90
91### Common requirements
92
93Install the following packages from your package repository:
94
95- `git`
96- `gcc` or `clang` or `mingw32-gcc` or `mingw64-gcc` (C-compiler; very likely gcc is already present)
97- `build-essential` (on Debian based distros (Debian, Ubuntu))
98- `cmake` (3.4.2 or later, use the latest version available from the repository)
99- `rpm` (on Debian based distros (Debian, Ubuntu), needed for package build with `make package`)
100- `libusb-1.0`
101- `libusb-1.0-0-dev` (development headers for building)
102- `libgtk-3-dev` (_optional_, needed for `stlink-gui`)
103- `pandoc` (_optional_, needed for generating manpages from markdown)
104
105or execute (Debian-based systems only): `apt-get install gcc build-essential cmake libusb-1.0 libusb-1.0-0-dev libgtk-3-dev pandoc`
106
107(Replace gcc with the intended C-compiler if necessary or leave out any optional package not needed.)
108
109### Installation
110
1111. Open a new terminal console
1122. Create a new destination folder at a place of your choice e.g. at `~/git`: `mkdir $HOME/git`
1133. Change to this directory: `cd ~/git`
1144. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`
115
116### Building
117
118#### Installation:
119
1201. Change into the project source directory: `cd stlink`
1212. Run `make clean` -- required by some linux variants.
1223. Run `make release` to create the _Release_ target
1234. Run `make install` to full install the package with complete system integration
1245. Run `make debug` to create the _Debug_ target (_optional_)<br />
125   The debug target is only necessary in order to modify the sources and to run under a debugger.
1266. Run `make package`to build a Debian Package. The generated packages can be found in the subdirectory `./build/dist`.
127
128As an option you may also install to an individual user-defined folder e.g `$HOME` with `make install DESTDIR=$HOME`.
129
130#### Removal:
131
1321. Run `make uninstall` to perform a clean uninstall of the package from the system.
1332. Run `make clean` to clean the build-folder within the project source and remove all compiled and linked files and libraries.
134
135### Cross-Building for Windows
136
137Install the following packages from your package repository:
138
139- `mingw-w64`
140- `mingw-w64-common`
141- `mingw-w64-i686-dev`
142- `mingw-w64-x86-64-dev`
143
144After following the steps for installation above, proceed with from the build dircetory itself:
145
146```sh
147$ sudo sh ./cmake/packaging/windows/generate_binaries.sh
148```
149
150The generated zip-packages can be found in the subdirectory `./build/dist`.
151
152### Set device access permissions and the role of udev
153
154By default most distributions don't allow access to USB devices.
155In this context udev rules, which create devices nodes, are necessary to run the tools without root permissions.
156To achieve this you need to ensure that the group `plugdev` exists and the user who is trying to access these devices is a member of this group.
157
158Within the sourcefolder of the project, these rules are located in the subdirectory `config/udev/rules.d` and are automatically installed along with `sudo make install` on linux.
159Afterwards it may be necessary to reload the udev rules:
160
161```sh
162$ sudo cp -a config/udev/rules.d/* /etc/udev/rules.d/
163$ sudo udevadm control --reload-rules
164$ sudo udevadm trigger
165```
166
167udev will now create device node files, e.g. `/dev/stlinkv3_XX`, `/dev/stlinkv2_XX`, `/dev/stlinkv1_XX`.
168
169### Special note on the use of STLink/V1 programmers (legacy):
170
171As the STLINKV1's SCSI emulation is somehow broken, the best advice possibly is to tell your operating system to completely ignore it.<br />
172Choose one of the following options _before_ connecting the device to your computer:
173
174- `modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i`
175- _OR_
176  1. `echo "options usb-storage quirks=483:3744:i" >> /etc/modprobe.conf`
177  2. `modprobe -r usb-storage && modprobe usb-storage`
178- _OR_
179  1. `cp stlink_v1.modprobe.conf /etc/modprobe.d`
180  2. `modprobe -r usb-storage && modprobe usb-storage`
181
182## macOS
183
184### Common requirements
185
186The best and recommended way is to install a package manager for open source software,
187either [homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/).
188
189Then install the following dependencies from the package repository:
190
191- `git`
192- `gcc` or `llvm` (for clang) (C-compiler)
193- `cmake`
194- `libusb`
195- `gtk+3` or `gtk3` (_optional_, needed for `stlink-gui`)
196
197To do this with only one simple command, type:
198
199- for homebrew:
200  - with gcc: `sudo brew install git gcc cmake libusb gtk+3` or
201  - with clang: `sudo brew install git llvm cmake libusb gtk+3` or
202- for MacPorts:
203  - with gcc: `sudo port install git gcc10 cmake libusb gtk3` or
204  - with clang: `sudo port install git llvm-10 cmake libusb gtk3`
205
206### Installation
207
2081. Open a new terminal window
2092. Create a new destination folder at a place of your choice e.g. at `~/git`: `mkdir $HOME/git`
2103. Change to this directory: `cd ~/git`
2114. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`
212
213### Building
214
2151. Change into the project source directory: `cd stlink`
2162. Run `make clean` to clean remnants of any previous builds.
2173. Run `make release` to create the _Release_ target
2184. Run `make debug` to create the _Debug_ target (_optional_)<br />
219   The debug target is only necessary in order to modify the sources and to run under a debugger.
220
221## Build options
222
223### Build using a different directory for shared libs
224
225To put the compiled shared libs into a different directory during installation,
226you can use the cmake option `cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" ..`.
227
228### Standard installation directories
229
230The cmake build system of this toolset includes `GNUInstallDirs` to define GNU standard installation directories.
231This module provides install directory variables as defined by the GNU Coding Standards.
232
233Below are the preset default cmake options, which apply if none of these options are redefined:
234
235- `-DCMAKE_INSTALL_SYSCONFDIR=/etc`
236- `-DCMAKE_INSTALL_PREFIX=/usr/local`
237
238Author: nightwalker-87
239