2020-02-26 19:32:55 +00:00
# Compiling from sources
2020-03-23 18:11:18 +00:00
## General package requirements
2016-10-22 08:18:33 +00:00
2020-03-23 18:11:18 +00:00
* cmake (v2.8.7 or later)
2020-02-26 19:32:55 +00:00
* C compiler (gcc, clang or mingw)
2020-03-23 18:11:18 +00:00
* libusb-1.0 (v1.0.13 or later)
* libusb-dev-1.0 (v1.0.13 or later)
* pandoc _(optional; for generating manpages from markdown)_
2016-10-22 08:18:33 +00:00
2016-10-29 10:08:39 +00:00
Run from the root of the source directory:
```
$ make release
$ make debug
```
2020-03-23 18:11:18 +00:00
The debug target should only be necessary for people who want to modify the sources and run under a debugger.
2016-10-29 10:08:39 +00:00
The top level Makefile is just a handy wrapper for:
2016-10-22 08:18:33 +00:00
```
$ mkdir build & & cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ make
```
2020-03-23 18:11:18 +00:00
You may install to a user folder e.g `$HOME` :
2016-10-29 10:08:39 +00:00
```
2017-02-20 17:45:07 +00:00
$ cd build/Release; make install DESTDIR=$HOME
2016-10-29 10:08:39 +00:00
```
2020-03-23 18:11:18 +00:00
Or system-wide:
2016-10-29 10:08:39 +00:00
```
2017-02-20 17:45:07 +00:00
$ cd build/Release; sudo make install
2016-10-29 10:08:39 +00:00
```
2016-10-22 08:18:33 +00:00
2020-03-23 18:11:18 +00:00
## Linux / Unix
2016-10-22 08:18:33 +00:00
## Common requirements
2020-03-23 18:11:18 +00:00
* `build-essential`
2016-10-22 08:18:33 +00:00
* `cmake`
2020-03-23 18:11:18 +00:00
* `libusb-1.0`
* `libusb-1.0-0-dev` (development headers for building, _only on debian based distros_ )
* `libgtk-3-dev` _(optional; required for `stlink-gui`)_
As of today several distributions namely:
- CentOS 6, 7, 8
- Debian 8, 9, 10, sid
- Fedora 30, 31, Rawhide
- NetBSD 7.2, 8.1, 9.0
- openSUSE Leap 15.1, Leap 15.2
- Ubuntu 14.04 LTS, 16.04 LTS, 18.04 LTS, 19.10
provide packages for libusb 0.1 and libusb 1.0.
**Please ensure that the correct version 1.0 is installed.**
Other relevant distributions appear to have packages named _libusb-compat-0.1_ or alike to distinguish from libusb packages based on version 1.0.x.
2016-10-22 08:18:33 +00:00
2016-10-29 10:03:58 +00:00
### Fixing cannot open shared object file
When installing system-wide (`sudo make install`) the dynamic library cache needs to be updated with the command `ldconfig` .
2020-03-23 18:11:18 +00:00
2016-10-22 08:18:33 +00:00
## Permissions with udev
2020-03-23 18:11:18 +00:00
Make sure you install udev files which are necessary to run the tools without root permissions.
By default most distributions don't allow access to USB devices.
The udev rules create devices nodes and set the group of this to `stlink` .
2016-10-22 08:18:33 +00:00
2020-03-23 18:11:18 +00:00
The rules are located in the `etc/udev/rules.d` directory.
You will need to copy it to /etc/udev/rules.d, and then either execute as root (or reboot your machine):
2016-10-22 08:18:33 +00:00
```
$ udevadm control --reload-rules
$ udevadm trigger
```
2020-03-23 18:11:18 +00:00
Udev will now create device node files `/dev/stlinkv2_XX` , `/dev/stlinkv1_XX` .
**You need to make sure the `stlink` group exists and the user, who is trying to access, is added to this group.**
2016-10-22 08:18:33 +00:00
### Note for STLINKv1 usage
2020-03-23 18:11:18 +00:00
The STLINKv1's SCSI emulation is corrupted, so the best thing to do is tell your operating system to completely ignore it.
2016-10-22 08:18:33 +00:00
Options (do one of these before you plug it in)
2020-03-23 18:11:18 +00:00
* `modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i` or
1. `echo "options usb-storage quirks=483:3744:i" >> /etc/modprobe.conf`
2. `modprobe -r usb-storage && modprobe usb-storage`
* or
1. `cp stlink_v1.modprobe.conf /etc/modprobe.d`
2. `modprobe -r usb-storage && modprobe usb-storage`
2016-10-22 08:18:33 +00:00
### Build Debian Package
2017-01-14 14:05:26 +00:00
2020-03-23 18:11:18 +00:00
To build the debian package you need the additional packages `devscripts` and `debhelper` .
2016-10-22 08:18:33 +00:00
```
$ git archive --prefix=$(git describe)/ HEAD | bzip2 --stdout > ../libstlink_$(sed -En -e "s/.*\((.*)\).*/\1/" -e "1,1 p" debian/changelog).orig.tar.bz2
$ debuild -uc -us
```
2016-10-22 08:22:44 +00:00
2020-03-23 18:11:18 +00:00
## macOS
### Prerequisites
2016-10-22 08:22:44 +00:00
When compiling on a mac you need the following:
* A compiler toolchain (XCode)
2020-03-23 18:11:18 +00:00
* cmake
* **libusb 1.0**
2016-10-22 08:22:44 +00:00
2020-03-23 18:11:18 +00:00
The best way is to install [homebrew ](http://brew.sh ) which is a package manager for opensource software which is missing from the Apple App Store. Then install the dependencies:
2016-10-22 08:22:44 +00:00
```
brew install libusb cmake
```
Compile as described in the first section of this document.
2016-10-26 18:40:25 +00:00
2020-03-23 18:11:18 +00:00
2016-10-26 18:40:25 +00:00
## Build using different directories for udev and modprobe
2020-03-23 18:11:18 +00:00
To put the udev or the modprobe configuration files into a different directory during installation use the following cmake options:
2016-10-26 18:40:25 +00:00
```
$ cmake -DSTLINK_UDEV_RULES_DIR="/usr/lib/udev/rules.d" \
-DSTLINK_MODPROBED_DIR="/usr/lib/modprobe.d" ..
```
2017-01-28 10:30:30 +00:00
2020-03-23 18:11:18 +00:00
2017-09-08 12:00:45 +00:00
## Build using different directory for shared libs
2020-03-23 18:11:18 +00:00
To put the compiled shared libs into a different directory during installation you can use the following cmake option:
2017-09-08 12:00:45 +00:00
```
2020-03-23 18:11:18 +00:00
$ cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" ..
2017-09-08 12:00:45 +00:00
```
2017-01-28 10:30:30 +00:00
2020-03-23 18:11:18 +00:00
## Windows (MinGW64)
### Prerequisites
2017-01-28 10:30:30 +00:00
2020-03-23 18:11:18 +00:00
* 7zip
* cmake 2.8 or higher
2017-01-28 10:30:30 +00:00
* MinGW64 GCC toolchain (5.3.0)
2020-03-23 18:11:18 +00:00
2017-01-28 10:30:30 +00:00
### Installation
2020-03-23 18:11:18 +00:00
1. Install 7zip from < http: // www . 7-zip . org >
2017-01-28 10:30:30 +00:00
2. Install CMake from < https: // cmake . org / download >
3. Install MinGW64 from < https: // sourceforge . net / projects / mingw-w64 > (mingw-w64-install.exe)
4. Git clone or download stlink sourcefiles zip
2020-03-23 18:11:18 +00:00
2017-01-28 10:30:30 +00:00
### Building
Check and execute (in the script folder) `<source-dir>\scripts\mingw64-build.bat`
2020-03-23 18:11:18 +00:00
**NOTE:** when installing different toolchains make sure you edit the path in the `mingw64-build.bat` .
The build script currently uses `C:\Program Files\mingw-w64\x86_64-5.3.0-win32-sjlj-rt_v4-rev0\mingw64\bin`
2017-06-17 06:05:47 +00:00
2020-03-23 18:11:18 +00:00
## Windows (Visual Studio)
2017-06-17 06:05:47 +00:00
### Prerequisites
2020-03-23 18:11:18 +00:00
* 7zip
* cmake (tested with version 3.9.0-rc2)
* Visual Studio 2017 Community Edition (other versions will likely work but are untested; the Community Edition is free for open source
2017-06-17 06:05:47 +00:00
development)
2020-03-23 18:11:18 +00:00
2017-06-17 06:05:47 +00:00
### Installation
2020-03-23 18:11:18 +00:00
1. Install 7zip from < http: // www . 7-zip . org >
2017-06-17 06:05:47 +00:00
2. Install CMake from < https: // cmake . org / download >
3. Git clone or download stlink sourcefiles zip
2020-03-23 18:11:18 +00:00
2017-06-17 06:05:47 +00:00
### Building
2020-03-23 18:11:18 +00:00
These instructions are for a 32-bit version.
2017-06-17 06:05:47 +00:00
In a command prompt, change directory to the folder where the stlink files were cloned (or unzipped).
Make sure the build folder exists (`mkdir build` if not).
From the build folder, run cmake (`cd build; cmake ..`).
2020-03-23 18:11:18 +00:00
This will create a solution (stlink.sln) in the build folder.
Open it in Visual Studio, select the Solution Configuration (_Debug_ or _Release_ ) and build the solution normally (F7).
2017-06-17 06:05:47 +00:00
2020-03-23 18:11:18 +00:00
NOTES: This solution will link to the dll version of libusb-1.0.
To debug or run the executable, the dll version of libusb-1.0 must be either on the path, or in the same folder as the executable.
It can be copied from here: `build\3thparty\libusb-1.0.21\MS32\dll\libusb-1.0.dll` .
2017-06-17 06:05:47 +00:00
2019-05-11 17:41:57 +00:00
2020-03-23 18:11:18 +00:00
## Linux (MinGW64)
### Prerequisites
2019-05-11 17:41:57 +00:00
2020-03-23 18:11:18 +00:00
* 7zip
* cmake 2.8 or higher
2019-05-11 17:41:57 +00:00
* MinGW64 GCC toolchain (5.3.0)
2020-03-23 18:11:18 +00:00
2019-05-11 17:41:57 +00:00
### Installation (Debian / Ubuntu)
sudo apt install p7zip mingw-w64
2020-03-23 18:11:18 +00:00
2019-05-11 17:41:57 +00:00
### Building
2020-03-23 18:11:18 +00:00
These instructions are for a 32-bit version.
2019-05-11 17:41:57 +00:00
```sh
cd < source-dir >
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./cmake/linux-mingw32.cmake -S . -B ./build/linux-mingw32
cmake --build ./build/linux-mingw32 --target all
```