Merge pull request #1440 from a-michelis/feature/libusb_cmake

[feature] libusb-cmake as libusb provider and added support for MSVC
stlink-org · Jan 6, 2025 · e734619 · e734619
2 parents 733893a + 60536da
commit e734619
Show file tree

Hide file tree

Showing 4 changed files with 149 additions and 31 deletions.
diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml
@@ -188,6 +188,33 @@ jobs:
         run: sudo make package
       - name: sudo make uninstall
         run: sudo make uninstall && sudo make clean
+
+  job_windows_msvc:
+    name: windows MSVC
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: debug
+        run: |
+          mkdir build
+          mkdir build\\debug
+          cd build\\debug
+          cmake ..\\.. -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE="Debug"
+          cmake --build . --target ALL_BUILD
+      - name: make release
+        run: |
+          mkdir build\\release
+          cd build\\release
+          cmake ..\\.. -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE="Release"
+          cmake --build . --target ALL_BUILD
+      - name: make install
+        run: |
+          cd build\\release
+          cmake --build . --target INSTALL
+      - name: sudo make uninstall
+        run: |
+          cd build\\release
+          cmake --build . --target uninstall
 # Linux MinGW cross compliation
 
 # job_linux_22_04_cross:

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -96,6 +96,7 @@ endif()
 ###
 
 find_package(libusb REQUIRED)
+add_definitions(${LIBUSB_DEFINITIONS}) #only affects MSVC, For ssize-t
 
 ## Check for system-specific additional header files and libraries
 
@@ -262,15 +263,37 @@ set_target_properties(${STLINK_LIB_SHARED} PROPERTIES
                         OUTPUT_NAME ${PROJECT_NAME}
                         )
 
+# Since we're not using __declspec(dllexport), WINDOWS_EXPORT_ALL_SYMBOLS is mandatory for MSVC.
+# This call will only affect MSVC, compilers/OSes ignore it.
+# TODO: Use dllexport on the desired functions
+set_target_properties(${STLINK_LIB_SHARED} PROPERTIES
+        WINDOWS_EXPORT_ALL_SYMBOLS ON
+)
+
 # Link shared library
 if (WIN32)
     target_link_libraries(${STLINK_LIB_SHARED} ${LIBUSB_LIBRARY} ${SSP_LIB} wsock32 ws2_32)
 else ()
     target_link_libraries(${STLINK_LIB_SHARED} ${LIBUSB_LIBRARY} ${SSP_LIB})
 endif()
 
-install(TARGETS ${STLINK_LIB_SHARED} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
-
+# For MSVC:
+#    shared libraries (.dll) go to `bin`
+#    their Import Libraries (aka: ImpLibs; .lib files) go to `lib`
+if (MSVC)
+    install(TARGETS ${STLINK_LIB_SHARED}
+            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+            LIBRARY DESTINATION ${CMAKE_INSTALL_BINDIR}
+            ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+# For non-MSVC:
+#    shared libraries go to `lib`
+#    Archive destination is set to `lib` as failsafe
+else()
+    install(TARGETS ${STLINK_LIB_SHARED}
+            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+            LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+endif()
 
 ###
 # Static library

diff --git a/cmake/modules/Findlibusb.cmake b/cmake/modules/Findlibusb.cmake
@@ -9,6 +9,7 @@
 #  LIBUSB_DEFINITIONS   compiler switches required for using libusb
 
 include(FindPackageHandleStandardArgs)
+include(FetchContent)
 
 if (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD")                       # FreeBSD; libusb is integrated into the system
     # libusb header file
@@ -51,6 +52,42 @@ elseif (CMAKE_SYSTEM_NAME STREQUAL "OpenBSD")                   # OpenBSD; libus
         message(FATAL_ERROR "No libusb-1.0 library found on your system! Install libusb-1.0 from ports or packages.")
     endif()
 
+elseif (MSVC)      # Native Windows MSVC
+
+    set(libusb_FIND_REQUIRED OFF) # Will either find it or download it, there's no missing it.
+    set(LIBUSB_DEFINITIONS "-D_SSIZE_T_DEFINED" "-Dssize_t=int64_t") # fix for ill-defined ssize-t
+
+    # libusb header file
+    FIND_PATH(LIBUSB_INCLUDE_DIR
+            NAMES libusb.h
+            HINTS "C:/Program Files/libusb-1.0/include" "C:/Program Files (x86)/libusb-1.0/include"
+            PATH_SUFFIXES "libusb-1.0"
+    )
+
+    # libusb library
+    set(LIBUSB_NAME usb-1.0)
+    find_library(LIBUSB_LIBRARY
+            NAMES ${LIBUSB_NAME}
+            HINTS "C:/Program Files/libusb-1.0" "C:/Program Files (x86)/libusb-1.0"
+    )
+
+    FIND_PACKAGE_HANDLE_STANDARD_ARGS(libusb DEFAULT_MSG LIBUSB_LIBRARY LIBUSB_INCLUDE_DIR)
+    mark_as_advanced(LIBUSB_INCLUDE_DIR LIBUSB_LIBRARY)
+    if (NOT LIBUSB_FOUND)
+        message(STATUS "No libusb-1.0 not installed into your system. Downloading and building it from source")
+
+        FetchContent_Declare(
+                ${LIBUSB_NAME}
+                GIT_REPOSITORY https://github.com/libusb/libusb-cmake
+                GIT_TAG        v1.0.27-0
+        )
+
+        FetchContent_MakeAvailable(${LIBUSB_NAME})
+        set(LIBUSB_FOUND ON)
+        set(LIBUSB_INCLUDE_DIR "")
+        set(LIBUSB_LIBRARY ${LIBUSB_NAME})
+        mark_as_advanced(LIBUSB_FOUND LIBUSB_INCLUDE_DIR LIBUSB_LIBRARY)
+    endif()
 elseif (WIN32 OR (MINGW AND EXISTS "/etc/debian_version"))      # Windows OR cross-build with MinGW-toolchain on Debian
     # MinGW: 64-bit or 32-bit?
     if (CMAKE_SIZEOF_VOID_P EQUAL 8)
@@ -73,53 +110,42 @@ elseif (WIN32 OR (MINGW AND EXISTS "/etc/debian_version"))      # Windows OR cro
         else ()                                 # ... download the package
             message(STATUS "downloading libusb ${LIBUSB_WIN_VERSION}")
             file(DOWNLOAD
-                https://sourceforge.net/projects/libusb/files/libusb-1.0/libusb-${LIBUSB_WIN_VERSION}/libusb-${LIBUSB_WIN_VERSION}.7z/download
-                ${LIBUSB_WIN_ARCHIVE_PATH} EXPECTED_MD5 c72153fc5a32f3b942427b0671897a1a
-                )
+                    https://sourceforge.net/projects/libusb/files/libusb-1.0/libusb-${LIBUSB_WIN_VERSION}/libusb-${LIBUSB_WIN_VERSION}.7z/download
+                    ${LIBUSB_WIN_ARCHIVE_PATH} EXPECTED_MD5 c72153fc5a32f3b942427b0671897a1a
+            )
         endif()
 
         file(MAKE_DIRECTORY ${LIBUSB_WIN_OUTPUT_FOLDER})
 
         # Extract libusb package with cmake
         execute_process(
-            COMMAND ${CMAKE_COMMAND} -E tar xv ${LIBUSB_WIN_ARCHIVE_PATH}
-            WORKING_DIRECTORY ${LIBUSB_WIN_OUTPUT_FOLDER}
-            )
+                COMMAND ${CMAKE_COMMAND} -E tar xv ${LIBUSB_WIN_ARCHIVE_PATH}
+                WORKING_DIRECTORY ${LIBUSB_WIN_OUTPUT_FOLDER}
+        )
 
         # libusb header file
         FIND_PATH(LIBUSB_INCLUDE_DIR
-            NAMES libusb.h
-            HINTS ${LIBUSB_WIN_OUTPUT_FOLDER}/include
-            PATH_SUFFIXES libusb-1.0
-            NO_DEFAULT_PATH
-            NO_CMAKE_FIND_ROOT_PATH
-            )
-
-        if (MINGW OR MSYS)
-            # libusb library (static)
-            set(LIBUSB_NAME libusb-1.0)
-            find_library(LIBUSB_LIBRARY
-                NAMES ${LIBUSB_NAME}
-                HINTS ${LIBUSB_WIN_OUTPUT_FOLDER}/MinGW${ARCH}/static
+                NAMES libusb.h
+                HINTS ${LIBUSB_WIN_OUTPUT_FOLDER}/include
+                PATH_SUFFIXES libusb-1.0
                 NO_DEFAULT_PATH
                 NO_CMAKE_FIND_ROOT_PATH
-                )
-        else (MSVC)
-            # libusb library
-            set(LIBUSB_NAME libusb-1.0)
-            find_library(LIBUSB_LIBRARY
+        )
+
+
+        # libusb library (static)
+        set(LIBUSB_NAME libusb-1.0)
+        find_library(LIBUSB_LIBRARY
                 NAMES ${LIBUSB_NAME}
-                HINTS ${LIBUSB_WIN_OUTPUT_FOLDER}/MinGW${ARCH}/dll
+                HINTS ${LIBUSB_WIN_OUTPUT_FOLDER}/MinGW${ARCH}/static
                 NO_DEFAULT_PATH
                 NO_CMAKE_FIND_ROOT_PATH
-                )
-        endif()
+        )
     endif()
 
     FIND_PACKAGE_HANDLE_STANDARD_ARGS(libusb DEFAULT_MSG LIBUSB_INCLUDE_DIR LIBUSB_LIBRARY)
     mark_as_advanced(LIBUSB_INCLUDE_DIR LIBUSB_LIBRARY)
     message(STATUS "Missing libusb library has been installed")
-
 else ()                                                         # all other OS (unix-based)
     # libusb header file
     FIND_PATH(LIBUSB_INCLUDE_DIR

diff --git a/doc/compiling.md b/doc/compiling.md
@@ -1,7 +1,7 @@
 # Compiling from sources
 
 
-## Microsoft Windows (10, 11)
+## Microsoft Windows - MINGW (10, 11)
 
 ### Common Requirements
 
@@ -39,6 +39,48 @@ Depending on the flavour of compilation the final executables will be placed in
 [ST-LINK drivers](https://www.st.com/en/development-tools/stsw-link009.html) are required for programmers to work with `stlink`.
 
 
+## Microsoft Windows - MSVC (10, 11)
+
+### Common Requirements
+
+On Windows users should ensure that the following software is installed:
+
+- `git` (Required for building LibUSB if missing)
+- `7zip`
+- `cmake`
+- `MSVC` Compiler (Tested with Visual Studio 2022 and Build Tools for Visual Studio 2022)
+
+### Installation
+
+1. Install `Build Tools for Visual Studio` from <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022>
+2. Install `cmake` from <https://cmake.org/download/#latest> --> Binary distributions --> Windows x64 Installer<br />
+   Ensure that you add cmake to the $PATH system variable when following the instructions by the setup assistant.
+   Follow the installation instructions on the website.
+3. Fetch the project source files by running `git clone https://github.com/stlink-org/stlink.git` from the command-line (`cmd.exe`/`powershell.exe`)<br />
+   or download and extract (`7zip`) the latest stlink `.zip` release from the Release page on GitHub.
+
+### Building
+
+1. Open the command-line (`cmd.exe`/`powershell.exe`) with administrator privileges
+2. Move to the `stlink` directory with `cd C:\$Path-to-your-stlink-folder$\`
+3. Create a new `build` subdirectory and move into it with `cd .\build`.
+4. Configure the project, using the following command: `cmake -G "Visual Studio 17 2022" .. -DCMAKE_BUILD_TYPE="Release"`
+5. Build the project, using the following command: `cmake --build . --target ALL_BUILD`
+6. Install the project, using the following command: `cmake --build . --target INSTALL`
+7. Add the `bin` folder of the installation path (`C:\Program Files (x86)\stlink\bin`) to the `PATH` environment variables:
+   1. Run `SystemPropertiesAdvanced.exe`
+   2. press on `Environment Variables` button
+   3. On `System Variables` list, find and select `Path` variable
+   4. Press `Edit..` button bellow the list
+   5. On the new Window, press `New` button
+   6. On the new row, type the `bin` path of your installation (`C:\Program Files (x86)\stlink\bin`)
+   7. Press `OK` button to all three windows to save your changes
+
+**NOTE:**
+
+1. [ST-LINK drivers](https://www.st.com/en/development-tools/stsw-link009.html) are required for programmers to work with `stlink`.
+2. Package generation for MSVC is not yet implemented/tested.
+
 ## Linux
 
 ### Common requirements