diff options
Diffstat (limited to 'doc/compiling.md')
| -rw-r--r-- | doc/compiling.md | 109 |
1 files changed, 22 insertions, 87 deletions
diff --git a/doc/compiling.md b/doc/compiling.md index eef207f..804781f 100644 --- a/doc/compiling.md +++ b/doc/compiling.md @@ -1,74 +1,42 @@ # Compiling from sources -## Microsoft Windows (10, 8.1) +## Microsoft Windows (10, 11) ### Common Requirements On Windows users should ensure that the following software is installed: - `git` (_optional, but recommended_) -- `cmake` (3.17.0 or later) -- `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0 +- `cmake` +- `7-zip` +- `MinGW-w64` ### Installation 1. Install `git` from <https://git-scm.com/download/win> 2. Install `cmake` from <https://cmake.org/download><br /> Ensure that you add cmake to the $PATH system variable when following the instructions by the setup assistant. -3. Install - -- _EITHER_: **MinGW-w64** from <https://sourceforge.net/projects/mingw-w64> (mingw-w64-install.exe)<br /> -- _OR_: **MSVC toolchain** from Visual Studio Build Tools 2019 +3. Install MinGW-w64<br /> + Download **MinGW-w64** from <https://github.com/niXman/mingw-builds-binaries/releases/download/13.2.0-rt_v11-rev1/x86_64-13.2.0-release-win32-seh-msvcrt-rt_v11-rev1.7z>. Extract content to `C:\mingw-w64\` and add `C:\mingw-w64\bin\` to PATH-Variable.<br /> 4. Create a new destination folder at a place of your choice 5. Open the command-line (cmd.exe) and execute `cd C:\$Path-to-your-destination-folder$\` 6. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`from the command-line (cmd.exe)<br /> - or download the stlink zip-sourcefolder from the Release page on GitHub - -#### MSVC toolchain - minimal installation - -Visual Studio IDE is not necessary, only Windows SDK & build tools are required (~3,3GB). - -1. Open <https://visualstudio.microsoft.com/downloads/> -2. Navigate through menus as follows (might change overtime) - - `All downloads > Tools for Visual Studio 2019 > Build Tools for Visual Studio 2019 > Download` - -3. Start downloaded executable. After Visual Studio Installer bootstraps and main window pops up, open `Individual Components` tab, and pick - -- latest build tools (eg. `MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)`) -- latest Windows SDK (eg. `Windows 10 SDK (10.0.18362.0)`) - -4. After installation finishes, you can press `Launch` button in Visual Studio Installer's main menu. - - Thus you can open `Developer Command Prompt for VS 2019`. It is `cmd.exe` instance with adjusted PATHs including eg. `msbuild`. - - Alternatively, you can use `Developer Powershell for VS 2019` which is the same thing for `powershell.exe`. Both are available from Start menu. - - 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. + or download and extract the stlink zip-sourcefolder from the Release page on GitHub. ### Building #### MinGW-w64 -1. Use the command-line to move to the `scripts` directory within the source-folder: `cd stlink\scripts\` -2. Execute `./mingw64-build.bat` +1. Open command-line with administrator privileges +2. Move to the `stlink` directory +3. 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 /> +Per default the build script (currently) uses `C:\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. -#### MSVC toolchain - -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 file `stlink.sln` in the build folder. -Now, you can build whole `stlink` suite using following command: - -``` -msbuild /m /p:Configuration=Release stlink.sln -``` - Options: - `/m` - compilation runs in parallel utilizing multiple cores @@ -95,7 +63,7 @@ Install the following packages from your package repository: - `git` - `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) +- `cmake` - `rpm` (on Debian based distros (Debian, Ubuntu), needed for package build with `make package`) - `libusb-1.0` - `libusb-1.0-0-dev` (development headers for building) @@ -119,14 +87,18 @@ or execute (Debian-based systems only): `apt-get install gcc build-essential cma 1. Change into the project source directory: `cd stlink` 2. Run `make clean` -- required by some linux variants. -3. Run `make release` to create the _Release_ target -4. Run `make install` to full install the package with complete system integration +3. Run `make release` to create the _Release_ target. +4. Run `make install` to full install the package with complete system integration. This might require sudo permissions. 5. 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. -6. Run `make package`to build a Debian Package. The generated packages can be found in the subdirectory `./build/dist`. +6. Run `make package`to build a Debian Package. The generated packages can be found in the subdirectory `./build/Release/dist`. As an option you may also install to an individual user-defined folder e.g `$HOME` with `make install DESTDIR=$HOME`. +### How to avoid the error message: "Can not open shared object file" + +When installing system-wide (`sudo make install`) the dynamic library cache needs to be updated with the command `ldconfig`. + #### Removal: 1. Run `make uninstall` to perform a clean uninstall of the package from the system. @@ -159,7 +131,7 @@ Within the sourcefolder of the project, these rules are located in the subdirect Afterwards it may be necessary to reload the udev rules: ```sh -$ sudo cp -a config/udev/rules.d/* /etc/udev/rules.d/ +$ sudo cp -a config/udev/rules.d/* /lib/udev/rules.d/ $ sudo udevadm control --reload-rules $ sudo udevadm trigger ``` @@ -179,45 +151,6 @@ Choose one of the following options _before_ connecting the device to your compu 1. `cp stlink_v1.modprobe.conf /etc/modprobe.d` 2. `modprobe -r usb-storage && modprobe usb-storage` -## macOS - -### Common requirements - -The best and recommended way is to install a package manager for open source software, -either [homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/). - -Then install the following dependencies from the package repository: - -- `git` -- `gcc` or `llvm` (for clang) (C-compiler) -- `cmake` -- `libusb` -- `gtk+3` or `gtk3` (_optional_, needed for `stlink-gui`) - -To do this with only one simple command, type: - -- for homebrew: - - with gcc: `sudo brew install git gcc cmake libusb gtk+3` or - - with clang: `sudo brew install git llvm cmake libusb gtk+3` or -- for MacPorts: - - with gcc: `sudo port install git gcc10 cmake libusb gtk3` or - - with clang: `sudo port install git llvm-10 cmake libusb gtk3` - -### Installation - -1. Open a new terminal window -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/stlink-org/stlink.git` - -### Building - -1. Change into the project source directory: `cd stlink` -2. Run `make clean` to clean remnants of any previous builds. -3. Run `make release` to create the _Release_ target -4. 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. - ## Build options ### Build using a different directory for shared libs @@ -235,4 +168,6 @@ Below are the preset default cmake options, which apply if none of these options - `-DCMAKE_INSTALL_SYSCONFDIR=/etc` - `-DCMAKE_INSTALL_PREFIX=/usr/local` +Please refer to the related [cmake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) for details. + Author: nightwalker-87 |