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