From 27aa88821197d3ffe82baff4e971c3488ec39899 Mon Sep 17 00:00:00 2001 From: nightwalker-87 <15526941+Nightwalker-87@users.noreply.github.com> Date: Sat, 4 Apr 2020 13:03:22 +0200 Subject: [PATCH] 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) --- cmake/modules/FindLibUSB.cmake | 8 +- doc/compiling.md | 284 +++++++++++++++------------------ doc/version_support.md | 82 ++++++++++ include/stlink/stlinkusb.h | 20 +-- scripts/mingw64-build.bat | 2 +- 5 files changed, 230 insertions(+), 166 deletions(-) create mode 100644 doc/version_support.md diff --git a/cmake/modules/FindLibUSB.cmake b/cmake/modules/FindLibUSB.cmake index f88556205..c8f467902 100644 --- a/cmake/modules/FindLibUSB.cmake +++ b/cmake/modules/FindLibUSB.cmake @@ -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) diff --git a/doc/compiling.md b/doc/compiling.md index 2728c153b..0133981b1 100644 --- a/doc/compiling.md +++ b/doc/compiling.md @@ -1,224 +1,204 @@ # 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 -``` - -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: +* `7zip` +* `git` +* `cmake` (3.17.0 or later) +* `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0 -``` -$ mkdir build && cd build -$ cmake -DCMAKE_BUILD_TYPE=Debug .. -$ make -``` -You may install to a user folder e.g `$HOME`: +### Installation -``` -$ cd build/Release; make install DESTDIR=$HOME -``` +1. Install `7zip` from +2. Install `git` from +3. Install `cmake` from +4. Install + - _EITHER_: **MinGW-w64** from (mingw-w64-install.exe)
+ Ensure that you add MinGW to the $PATH system variable when following the instructions by the setup assistant.
+ - _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)
+ or download the stlink zip-sourcefolder from the Release page on GitHub -Or system-wide: -``` -$ cd build/Release; sudo make install -``` +### 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` -## Linux / Unix -## Common requirements +NOTE:
+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`.
+When installing different toolchains make sure to update the path in the `mingw64-build.bat`.
+This can be achieved by opening the .bat file with a common text editor. -* `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`)_ -As of today several distributions namely: +#### Visual Studio (32 bit) -- 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 +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 ..`). -provide packages for libusb 0.1 and libusb 1.0. +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). -**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. +NOTE:
+This solution will link to the dll version of libusb-1.0.y
+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 +### Common requirements -### Fixing cannot open shared object file +Install the following packages from your package repository: -When installing system-wide (`sudo make install`) the dynamic library cache needs to be updated with the command `ldconfig`. +* `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` -## Permissions with udev +(Replace gcc with the intended C-compiler if necessary or leave out any optional package not needed.) -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 +### Installation -The STLINKv1's SCSI emulation is corrupted, so the best thing to do is tell your operating system to completely ignore it. +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` -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` +### 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_)
+ The debug target is only necessary in order to modify the sources and to run under a debugger. -### Build Debian Package +The top level Makefile is just a handy wrapper for: -To build the debian package you need the additional packages `devscripts` and `debhelper`. +##### MinGW64: +```sh +$ mkdir build && cd build +$ cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_TOOLCHAIN_FILE=./cmake/linux-mingw64.cmake -S .. +$ make ``` -$ 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 +##### MinGW32: -When compiling on a mac you need the following: - -* A compiler toolchain (XCode) -* 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: - -``` -brew install libusb cmake +```sh +$ mkdir build && cd build +$ cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_TOOLCHAIN_FILE=./cmake/linux-mingw32.cmake -S .. +$ make ``` -Compile as described in the first section of this document. - - -## Build using different directories for udev and modprobe +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`. -To put the udev or the modprobe configuration files into a different directory during installation use the following cmake options: - -``` -$ cmake -DSTLINK_UDEV_RULES_DIR="/usr/lib/udev/rules.d" \ - -DSTLINK_MODPROBED_DIR="/usr/lib/modprobe.d" .. -``` +When installing system-wide, the dynamic library cache needs to be updated with the command `ldconfig`. -## Build using different directory for shared libs +### Build a Debian Package -To put the compiled shared libs into a different directory during installation you can use the following cmake option: +To build the debian package you need the following extra packages: `devscripts 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 ``` -$ cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" .. -``` - -## Windows (MinGW64) -### Prerequisites -* 7zip -* cmake 2.8 or higher -* MinGW64 GCC toolchain (5.3.0) +### 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`. -### Installation - -1. Install 7zip from -2. Install CMake from -3. Install MinGW64 from (mingw-w64-install.exe) -4. Git clone or download stlink sourcefiles zip +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 +``` -### Building +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. -Check and execute (in the script folder) `\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` +### 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. -## Windows (Visual Studio) -### Prerequisites +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. -* 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) +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` -### Installation -1. Install 7zip from -2. Install CMake from -3. Git clone or download stlink sourcefiles zip +Author: nightwalker-87 +----- -### Building +---- **The following content is outdated and unrevised!** ---- -These instructions are for a 32-bit version. +## Mac OS X -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 ..`). +When compiling on a mac you need the following: -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). +* A compiler toolchain (XCode) +* CMake +* Libusb 1.0 -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`. +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 +``` -## Linux (MinGW64) -### Prerequisites +Compile as described in the first section of this document. -* 7zip -* cmake 2.8 or higher -* MinGW64 GCC toolchain (5.3.0) +## Build using different directories for udev and modprobe -### Installation (Debian / Ubuntu) +To put the udev or the modprobe configuration files into a different directory +during installation you can use the following cmake options: -sudo apt install p7zip mingw-w64 +``` +$ cmake -DSTLINK_UDEV_RULES_DIR="/usr/lib/udev/rules.d" \ + -DSTLINK_MODPROBED_DIR="/usr/lib/modprobe.d" .. +``` -### Building +## Build using different directory for shared libs -These instructions are for a 32-bit version. +To put the compiled shared libs into a different directory during installation +you can use the following cmake option: -```sh -cd -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" .. ``` diff --git a/doc/version_support.md b/doc/version_support.md new file mode 100644 index 000000000..963ca2988 --- /dev/null +++ b/doc/version_support.md @@ -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.
+Up on compiling c-make will check **automatically**, whether `libusb` 1.0.20 or later is present.
+If this is not the case, the installation routine will download the latest version (1.0.23 at the time of writing).
+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
version | cmake
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
version | cmake
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 diff --git a/include/stlink/stlinkusb.h b/include/stlink/stlinkusb.h index 4d904b0c5..633d82bd0 100644 --- a/include/stlink/stlinkusb.h +++ b/include/stlink/stlinkusb.h @@ -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 diff --git a/scripts/mingw64-build.bat b/scripts/mingw64-build.bat index 3f92ae8e0..773195410 100644 --- a/scripts/mingw64-build.bat +++ b/scripts/mingw64-build.bat @@ -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