Updated compiling doc & version support

- Added info on version support
- Updated compiling instructions
- Updated minGW-w64 gcc-TC to v8.1.0
- Minor formatting fixes

(Closes #896, #897, #899)
pull/912/head
nightwalker-87 2020-04-04 13:03:22 +02:00
rodzic d3ad0c9034
commit 27aa888211
5 zmienionych plików z 251 dodań i 187 usunięć

Wyświetl plik

@ -6,13 +6,13 @@
# LIBUSB_LIBRARY - The libraries needed to use libusb
# LIBUSB_DEFINITIONS - Compiler switches required for using libusb
# FreeBSD
if (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD")
if (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD") # FreeBSD
FIND_PATH(LIBUSB_INCLUDE_DIR NAMES libusb.h
HINTS
/usr/include
)
else ()
else () # other OS
FIND_PATH(LIBUSB_INCLUDE_DIR NAMES libusb.h
HINTS
/usr
@ -22,6 +22,8 @@ else ()
)
endif()
# macOS
if (APPLE)
set(LIBUSB_NAME libusb-1.0.a)
elseif(MSYS OR MINGW)

Wyświetl plik

@ -1,122 +1,180 @@
# Compiling from sources
## General package requirements
* cmake (v2.8.7 or later)
* C compiler (gcc, clang or mingw)
* libusb-1.0 (v1.0.13 or later)
* libusb-dev-1.0 (v1.0.13 or later)
* pandoc _(optional; for generating manpages from markdown)_
## Microsoft Windows (10, 8.1)
### Common Requirements
Run from the root of the source directory:
On Windows users should ensure that the following software is installed:
```
$ make release
$ make debug
```
* `7zip`
* `git`
* `cmake` (3.17.0 or later)
* `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0
### Installation
1. Install `7zip` from <https://www.7-zip.org>
2. Install `git` from <https://git-scm.com/download/win>
3. Install `cmake` from <https://cmake.org/download>
4. Install
- _EITHER_: **MinGW-w64** from <https://sourceforge.net/projects/mingw-w64> (mingw-w64-install.exe)<br />
Ensure that you add MinGW to the $PATH system variable when following the instructions by the setup assistant.<br />
- _OR_: **Visual Studio 2017 CE** (other versions will likely work as well, but are untested; the Community edition is free for open source
development)
5. Create a new destination folder at a place of your choice
6. Open the command-line (cmd.exe) and execute `cd C:\$Path-to-your-destination-folder$\`
7. Fetch the project sourcefiles by running `git clone https://github.com/texane/stlink.git`from the command-line (cmd.exe)<br />
or download the stlink zip-sourcefolder from the Release page on GitHub
### Building
#### MinGW64
1. Use the command-line to move to the `scripts` directory within the source-folder: `cd stlink\scripts\`
2. Execute `./mingw64-build.bat`
NOTE:<br />
Per 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 />
When installing different toolchains make sure to update the path in the `mingw64-build.bat`.<br />
This can be achieved by opening the .bat file with a common text editor.
#### Visual Studio (32 bit)
1. In a command prompt, change the directory to the folder where the stlink files were cloned (or unzipped) to.
2. Make sure the build folder exists (`mkdir build` if not).
3. From the build folder, run cmake (`cd build; cmake ..`).
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).
NOTE:<br />
This solution will link to the dll version of libusb-1.0.y<br />
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.<br />
It can be copied from here: `build\3thparty\libusb-1.0.21\MS32\dll\libusb-1.0.dll`.
## Linux
### Common requirements
Install the following packages from your package repository:
* `gcc` or `clang` or `mingw32-gcc` or `mingw64-gcc` (C-compiler; very likely gcc is already present)
* `build-essential` (on Debian based distros (debian, ubuntu))
* `cmake` (3.4.2 or later, use the latest version available from the repository)
* `libusb-1.0`
* `libusb-1.0-0-dev` (development headers for building)
* `libgtk-3-dev` (_optional_, needed for `stlink-gui`)
* `pandoc` (_optional_, needed for generating manpages from markdown)
or execute (Debian-based systems only): `apt-get install gcc build-essential cmake libusb-1.0 libusb-1.0-0-dev libgtk-3-dev pandoc`
(Replace gcc with the intended C-compiler if necessary or leave out any optional package not needed.)
### Installation
1. Open a new terminal console
2. Create a new destination folder at a place of your choice e.g. at `~/git`: `mkdir $HOME/git`
3. Change to this directory: `cd ~/git`
4. Fetch the project sourcefiles by running `git clone https://github.com/texane/stlink.git`
### Building
1. Change into the project source directory: `cd stlink`
2. Run `make release` to create the _Release_ target
3. Run `make debug` to create the _Debug_ target (_optional_)<br />
The debug target is only necessary in order to modify the sources and to run under a debugger.
The debug target should only be necessary for people who want to modify the sources and run under a debugger.
The top level Makefile is just a handy wrapper for:
```
##### MinGW64:
```sh
$ mkdir build && cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_TOOLCHAIN_FILE=./cmake/linux-mingw64.cmake -S ..
$ make
```
You may install to a user folder e.g `$HOME`:
##### MinGW32:
```
$ cd build/Release; make install DESTDIR=$HOME
```sh
$ mkdir build && cd build
$ cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_TOOLCHAIN_FILE=./cmake/linux-mingw32.cmake -S ..
$ make
```
Or system-wide:
As an alternative you may also install
- to a user folder e.g `$HOME` with `cd build/Release && make install DESTDIR=$HOME`
- or system wide with `cd build/Release && sudo make install`.
```
$ cd build/Release; sudo make install
```
When installing system-wide, the dynamic library cache needs to be updated with the command `ldconfig`.
## Linux / Unix
## Common requirements
### Build a Debian Package
* `build-essential`
* `cmake`
* `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`)_
To build the debian package you need the following extra packages: `devscripts debhelper`.
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.
### 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`.
## Permissions with udev
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`.
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):
```
$ udevadm control --reload-rules
$ udevadm trigger
```
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.**
### Note for STLINKv1 usage
The STLINKv1's SCSI emulation is corrupted, so the best thing to do is tell your operating system to completely ignore it.
Options (do one of these before you plug it in)
* `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`
### Build Debian Package
To build the debian package you need the additional packages `devscripts` and `debhelper`.
```
```sh
$ 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
```
## macOS
### Prerequisites
### Set permissions with udev
By default most distributions don't allow access to USB devices.
Therefore make sure you install udev files which are necessary to run the tools without root permissions.
udev rules create devices nodes and set the group of these to `stlink`.
The rules are located in the subdirectory `etc/udev/rules.d` within the sourcefolder.
Copy them to the directory path `/etc/udev/rules.d` and subsequently reload the udev rules:
```sh
$ cp etc/udev/rules.d /etc/udev/rules.d
$ udevadm control --reload-rules
$ udevadm trigger
```
Udev will now create device node files `/dev/stlinkv2_XX`, `/dev/stlinkv1_XX`.
You need to ensure that the group `stlink` exists and the user who is trying to access these devices is a member of this group.
### Note on the use of STLink-v1 programmers:
At the time of writing the STLink-v1 has mostly been replaced with the newer generation STLink-v2 programmers and thus is only rarely used.
As there are some caveats as well, we recommend to use the STLink-v2 programmers if possible.
To be more precise, the STLINKv1's SCSI emulation is somehow broken, so the best advice possibly is to tell your operating system to completely ignore it.
Choose on of the following options _before_ connecting the device to your computer:
* `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`
Author: nightwalker-87
-----
---- **The following content is outdated and unrevised!** ----
## Mac OS X
When compiling on a mac you need the following:
* A compiler toolchain (XCode)
* cmake
* **libusb 1.0**
* CMake
* Libusb 1.0
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:
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:
```
brew install libusb cmake
@ -127,7 +185,8 @@ Compile as described in the first section of this document.
## Build using different directories for udev and modprobe
To put the udev or the modprobe configuration files into a different directory during installation use the following cmake options:
To put the udev or the modprobe configuration files into a different directory
during installation you can use the following cmake options:
```
$ cmake -DSTLINK_UDEV_RULES_DIR="/usr/lib/udev/rules.d" \
@ -137,88 +196,9 @@ $ cmake -DSTLINK_UDEV_RULES_DIR="/usr/lib/udev/rules.d" \
## Build using different directory for shared libs
To put the compiled shared libs into a different directory during installation you can use the following cmake option:
To put the compiled shared libs into a different directory during installation
you can use the following cmake option:
```
$ cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" ..
```
## Windows (MinGW64)
### Prerequisites
* 7zip
* cmake 2.8 or higher
* MinGW64 GCC toolchain (5.3.0)
### Installation
1. Install 7zip from <http://www.7-zip.org>
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
### Building
Check and execute (in the script folder) `<source-dir>\scripts\mingw64-build.bat`
**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`
## Windows (Visual Studio)
### Prerequisites
* 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
development)
### Installation
1. Install 7zip from <http://www.7-zip.org>
2. Install CMake from <https://cmake.org/download>
3. Git clone or download stlink sourcefiles zip
### Building
These instructions are for a 32-bit version.
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 ..`).
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).
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`.
## Linux (MinGW64)
### Prerequisites
* 7zip
* cmake 2.8 or higher
* MinGW64 GCC toolchain (5.3.0)
### Installation (Debian / Ubuntu)
sudo apt install p7zip mingw-w64
### Building
These instructions are for a 32-bit version.
```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
$ cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" ..
```

Wyświetl plik

@ -0,0 +1,82 @@
Sources: [pkgs.org - libusb](https://pkgs.org/search/?q=libusb) & [pkgs.org - cmake](https://pkgs.org/search/?q=cmake) (as of Mar 2020):
## Supported Operating Systems
### Microsoft Windows
On Windows users should ensure that cmake 3.17.0 is installed.<br />
Up on compiling c-make will check **automatically**, whether `libusb` 1.0.20 or later is present.<br />
If this is not the case, the installation routine will download the latest version (1.0.23 at the time of writing).<br />
Thus no user interaction regarding libusb is necessary.
* Windows 10
* Windows 8.1
### Apple macOS
On macOS users should ensure that cmake 3.17.0 is installed.
--> libusb Installation routine: (TBD) Work in progress...
* macOS 10.15 Catalina
* macOS 10.14 Mojave
* macOS 10.13 High Sierra
### Linux-/Unix-based:
| Operating System | libusb<br />version | cmake<br />version | Notes |
| --- | --- | --- | --- |
| Alpine Edge | 1.0.23 | 3.17.0 | |
| ALT Linux Sisyphus | 1.0.23 | 3.17.0 | |
| Arch Linux | 1.0.23 | 3.17.0 | |
| Fedora Rawhide | 1.0.23 | 3.17.0 | named `libusbx`, but `libusb`-codebase is used |
| KaOS | 1.0.23 | 3.17.0 | |
| OpenMandriva Cooker | 1.0.23 | 3.17.0 | |
| PCLinuxOS | 1.0.23 | 3.17.0 | named `lib64usb1.0_0-1.0.23-1pclos2019.x86_64` |
| Slackware Current | 1.0.23 | 3.17.0 | |
| Solus | 1.0.23 | 3.16.5 | |
| Debian Sid | 1.0.23 | 3.16.3 | |
| OpenMandriva Lx 4.1 | 1.0.23 | 3.16.3 | |
| Ubuntu 20.04 LTS (Focal Fossa) | 1.0.23 | 3.16.3 | |
| openSUSE Tumbleweed | 1.0.23 | 3.16.2 | |
| Alpine 3.11 | 1.0.23 | 3.15.5 | |
| Ubuntu 19.10 (Eoan Ermine) | 1.0.23 | 3.13.4 | |
| Mageia Cauldron | 1.0.22 | 3.17.0 | |
| NetBSD 9.0 | 1.0.22 | 3.16.1 | |
| NetBSD 8.1 | 1.0.22 | 3.16.1 | |
| NetBSD 7.2 | 1.0.22 | 3.16.1 | |
| Alpine 3.10 | 1.0.22 | 3.14.5 | |
| Fedora 31 | 1.0.22 | 3.14.5 | named `libusbx`, but `libusb`-codebase is used |
| Mageia 7.1 | 1.0.22 | 3.14.3 | |
| Fedora 30 | 1.0.22 | 3.14.2 | named `libusbx`, but `libusb`-codebase is used |
| Debian 10 (Buster) | 1.0.22 | 3.13.4 | |
| Alpine 3.9 | 1.0.22 | 3.13.0 | |
| CentOS 8 | 1.0.22 | 3.11.4 | named `libusbx`, but `libusb`-codebase is used |
| openSUSE Leap 15.2 | 1.0.21 | 3.15.5 | |
| openSUSE Leap 15.1 | 1.0.21 | 3.10.2 | |
| Ubuntu 18.04 LTS (Bionic Beaver) | 1.0.21 | 3.10.2 | |
| Debian 9 (Stretch) | 1.0.21 | 3.7.2 | |
| Slackware 14.2 | **1.0.20** | 3.5.2 | |
| Ubuntu 16.04 LTS (Xenial Xerus) | **1.0.20** | 3.5.1 | |
| OpenMandriva Lx 3.0 | **1.0.20** | **3.4.2** | |
| FreeBSD 13 | **1.0.16** - 1.0.18 | 3.15.5 | linux_libusb-13.0r358841 (integrated) |
| FreeBSD 12 | **1.0.16** - 1.0.18 | 3.15.5 | linux_libusb-11.0r261448_4 (integrated) |
| FreeBSD 11 | **1.0.16** - 1.0.18 | 3.15.5 | linux_libusb-11.0r261448_4 (integrated) |
## Unsupported Operating Systems as of Release 1.6.1 (2020)
| Operating System | libusb<br />version | cmake<br />version | End of OS-Support | Notes |
| --- | --- | --- | --- | --- |
| CentOS 7 | 1.0.21 | **2.8.12.2** | | named `libusbx`, but `libusb`-codebase is used |
| Debian 8 (Jessie) | 1.0.**19** | 3.0.2 | Jun 2020 |
| Ubuntu 14.04 LTS (Trusty Tahr) | 1.0.**17** | **2.8.12.2** | Apr 2019 |
| CentOS 6 | 1.0.**9** | **2.8.12.2** | Dec 2020 | named `libusbx`, but `libusb`-codebase is used |
| Slackware 14.1 | 1.0.**9** | **2.8.12** | |
| Slackware 14.0 | 1.0.**9** | **2.8.8** | |
_All other operating systems which are not listed are unsupported._
Author: nightwalker-87

Wyświetl plik

@ -22,25 +22,25 @@
*/
#if defined (__FreeBSD__)
#if !defined ( LIBUSBX_API_VERSION )
#define LIBUSBX_API_VERSION LIBUSB_API_VERSION
#elif !defined (LIBUSB_API_VERSION)
#error unsupported libusb version
#endif
#if !defined ( LIBUSBX_API_VERSION )
#define LIBUSBX_API_VERSION LIBUSB_API_VERSION
#elif !defined (LIBUSB_API_VERSION)
#error unsupported libusb version
#endif
#endif
#if defined (__FreeBSD__)
#define MINIMAL_API_VERSION 0x01000102
#define MINIMAL_API_VERSION 0x01000102 // v1.0.16
#elif defined (__linux__)
#define MINIMAL_API_VERSION 0x01000104
#define MINIMAL_API_VERSION 0x01000104 // v1.0.20
#elif defined (__APPLE__)
#define MINIMAL_API_VERSION 0x01000104
#define MINIMAL_API_VERSION 0x01000104 // v1.0.20
#elif defined (_WIN32)
#define MINIMAL_API_VERSION 0x01000106
#define MINIMAL_API_VERSION 0x01000104 // v1.0.20
#endif
#if ( LIBUSB_API_VERSION < MINIMAL_API_VERSION )
#error unsupported libusb version
#error unsupported libusb version
#endif
#endif // STLINKUSB_H

Wyświetl plik

@ -1,5 +1,5 @@
@echo off
set PATH=C:\Program Files (x86)\CMake\bin;C:\Program Files\CMake\bin;C:\Program Files\mingw-w64\x86_64-5.3.0-win32-sjlj-rt_v4-rev0\mingw64\bin;%PATH%
set PATH=C:\Program Files (x86)\CMake\bin;C:\Program Files\CMake\bin;C:\Program Files\mingw-w64\x86_64-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw64\bin;%PATH%
cmake -G "MinGW Makefiles" ..
mingw32-make
mingw32-make install DESTDIR=_install