Headers needed for compiling with libstlink.so.1.6.1 not included in installed headers

[tabemann]

Thank you for giving feedback to the stlink project.

In order to allow developers and other contributors to isolate and target your respective issue, please take some time to fill out each of the following items appropriate to your specific problem:

• Programmer/board type: any
• Programmer firmware version: any
• Operating system and version: Linux 5.5.0-1-amd64
• Stlink tools version and/or git commit hash: v1.6.1, from .tar.gz
• Stlink commandline tool name: any
• Target chip (and board if applicable): any

Futher we kindly ask you to describe the detected problem as detailed as possible and to add debug output if available, by using the following template:

Commandline-Output:

tabemann@sirius:~/projects/swdcom_z$ make
gcc -O0 -g -I/usr/local/include -I/usr/local/include/stlink -L/usr/local/lib -o swd2 swd2.c -lstlink
In file included from /usr/local/include/stlink.h:296,
                 from swd2.c:29:
/usr/local/include/stlink/sg.h:11:10: fatal error: libusb_settings.h: No such file or directory
   11 | #include "libusb_settings.h"
      |          ^~~~~~~~~~~~~~~~~~~
compilation terminated.
make: *** [Makefile:9: swd2] Error 1
tabemann@sirius:~/projects/swdcom_z$ sudo cp ~/Downloads/stlink-1.6.1/src/libusb_settings.h /usr/local/include/stlink


...

tabemann@sirius:~/projects/swdcom_z$ sudo cp ~/Downloads/stlink-1.6.1/src/usb.h /usr/local/include/stlink

Expected/description:

Header files should not have to be copied from src to /usr/local/include/stlink in order for code using libstlink to compile.

NOTICE: This bug report may be closed without further notice, if not enough information is provided!

Thank you for your support.

The stlink project maintainers

[Crest]

I ran into the exact same problem on FreeBSD 12.1/amd64 in stlink 1.5 all headers required to use the shared library were installed into /usr/local/include. In stlink 1.6.1 these are missing. At the time i assumed this to be an operating system specific packaging problem and filed the bug report here: FreeBSD PR #247225.

At least these headers from src/ are required to use libstlink:

• sg.h
• libusb_settings.h
• logging.h
• usb.h

[Nightwalker-87]

They are included in our top-level CMakeLists.txt :

set(STLINK_HEADERS
        inc/backend.h
        src/stlink-lib/commands.h
        src/stlink-lib/libusb_settings.h
        src/stlink-lib/reg.h
        inc/stlink.h
        src/stlink-lib/chipid.h
        src/stlink-lib/flash_loader.h
        src/stlink-lib/logging.h
        src/stlink-lib/md5.h
        src/stlink-lib/sg.h
        src/stlink-lib/usb.h
        )

set(STLINK_SOURCE
        src/common.c
        src/stlink-lib/chipid.c
        src/stlink-lib/flash_loader.c
        src/stlink-lib/logging.c
        src/stlink-lib/md5.c
        src/stlink-lib/sg.c
        src/stlink-lib/usb.c
        )

@tabemann @Crest : Your gcc include flags are wrong. This is likely the reason why it fails. Please let me know where these settings come from so we are able to fix it.

[tabemann]

The include options I am using are -I/usr/local/include -I/usr/local/include/stlink . Note that with those options it works out of the box with stlink 1.6.0 compiled from .tar.gz source (i.e. without any Debian packaging shenanigans).

[Nightwalker-87]

Yes, but there were changes to that, this is why I asked where they come from.

[tabemann]

What do you mean by "there were changes to that" - the include options were directly provided to gcc without any intermediary ./configure type system? The only changes that were made were to copy the relevant header files from src into /usr/local/include/stlink after initial attempts at compilation failed due to missing header files. Note that on my end I did not modify CMakeLists.txt but rather directly used sudo cp to copy the files into /usr/local/include/stlink.

[Nightwalker-87]

The include directories changed. However compilation was successfully tested on several systems before releasing v1.6.1 as long as instructions in /doc/compiling.md are being followed. As the command sudo cp is not part of it and the destination directory is not correct for this version, it is likely the reason why compilation fails on your side. Please follow our documentation when installing from source. Any custom changes may not see any support as they are unofficial and not tested.

[tabemann]

I followed the instructions in /doc/compiling.md for compilation from source on Linux up until `make release`. After that point, as there were no apparent directions for installation aside from by generating a Debian package and installing that, I ran `make install` as that is the typical means of installing programs written in C that are compiled from source, and it appeared to work, except that it omitted some include files. Note that this is not solely my problem as not only does Crest have this problem, but also the official Debian package for stlink 1.6.1 has this very same problem. The instances of `sudo cp` I mentioned were my attempts to fix the header files to make compilation work, which should not be necessary by any means.

…

On Sat, Jun 13, 2020 at 2:42 PM nightwalker-87 ***@***.***> wrote: The include directories changed. However compilation was successfully tested on several systems before releasing v1.6.1 as long as instructions in /doc/compiling.md are being followed. As the command sudo cp is not part of it and the destination directory is not correct for this version, it is likely the reason why compilation fails on your side. Please follow our documentation when installing from source. Any custom changes may not see any support as they are unofficial and not tested. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#982 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABDMC2EWU52X2R2U3KGU7J3RWPJAXANCNFSM4N4Z6QVQ> .

[Nightwalker-87]

Thanks for the more detailed description.

I ran make install as that is the typical means of installing programs written in C that are compiled from source, and it appeared to work, except that it omitted some include files.

Well this should not be the case of course, but did not appear to be the case during testing or was not noticed at all - I can't tell. I just found that the code excerpt posted earlier was from our develop branch and not from the master branch which indeed differs. Please try the recent develop branch and report if it resolves the described issue.

[Crest]

I ran pkgconf --cflags stlink to get -I/usr/local/include/stlink and added -I/usr/local/include because FreeBSD installs ports/packages under the /usr/local/ prefix.

I expect the libraries to install all headers required use them. The stlink programs (st-flash, st-info, st-util) build just fine. The problem is I want to make use of libstlink in my own code. The headers installed by stlink 1.6.1 are unusable for code that's not part of the stlink repo because they unconditionally #include <...> headers not installed at all. Those headers are kept only inside the src/ directory of the stlink repo.

[Crest]

This is the code I wrote calling into libstlink swd2.c. It uses the STLINK/V2 programmer a a fast console for the Mecrisp Stellaris Forth system. The terminal functions are in terminal.s. This approach has several advantages over the normal USART console:

• Faster than most USB<->serial adapters
• No need for a programmer and a serial adapter
• Flow control without handshaking lines on a 2wire (+gnd) bus
• 255 byte deep queues decouple the Forth system and host PC
• No chip specific USART setup code required.

The code works great with stlink 1.5.0 and I wanted to keep up with stlink development.

[Nightwalker-87]

As mentioned before, please test with develop and report back.

Before v1.6.1 not all headers were included via the top-level CMakeLists.txt. Some were included solely within the source files (somehow hardcoded, regarding file-paths within the project). In v1.6.1 we had some changes done to the project subfolder structure to simplify it and make it more comprehensible. Therefore some header files moved, which should have been considered throughout the includes. After v1.6.1 (develop branch) all relevant headers for the library should now be set in the top-level CMakeLists.txt.

[Crest]

I did uninstall the stlink package, cloned the stlink link repo, found myself already in the develop branch, compiled and installed it. Next I tried to build my own code that makes use of libstlink and got this error:

cc -O2 -pipe -std=c99 -Weverything -I/usr/local/include -I/usr/local/include/stlink -L/usr/local/lib -o swd2 swd2.c  -lstlink
In file included from swd2.c:23:
/usr/local/include/stlink.h:296:10: fatal error: 'sg.h' file not found
#include <sg.h>
         ^~~~~~
1 error generated.
*** Error code 1

Stop.
make: stopped in /home/crest/swdcom

The stlink.h header contains #include <sg.h> in line 296. In addition to sg.h the usb.h, libusb_settings.h and logging.h headers are also required by stlink.h but not installed.

[Nightwalker-87]

Please note that we don't provide support for any external use of the stlink-library. (There hasn't been any in the past either.)
I'm sorry to say that I can't currently invest any time in this besides addressing other open issues.
Rolling back to the old state is not an option, as it would oppose current efforts to improve the codebase itself.

Thus I'd recommend you to stay with the old version for your project, as this may not be addressed anytime soon - unless there are more active contributors to this project that help maintaining the code.

[Crest]

The fix would be to simply as install the required headers from src/ into /usr/local/include/stlink. Would you (or some other contributor) be willing to look at a pull request making this hopefully trivial change to the install target?

[Nightwalker-87]

@Crest: You can implement changes on your own fork for testing purposes and I can have a look, if you tell me to do so. Please don't open a PR yet. You can do so as soon as it appears to be compatible with all supported platforms and the recently updated project structure. I'd like to avoid several patches and a (possible) lengthy discussion of consecutive changes along a PR.

If you intend to take action related to this topic, please take a look at the current state of the develop branch and use the latter as a baseline for your intended changes. Make sure not to hardcode any path-prefixes and feel responsible for testing the proposed solution especially on Linux, FreeBSD and macOS to ensure compilation concludes successfully.

[Nightwalker-87]

Commits e506d33 and 3f20a25 do (at least partially) address this issue.
Executing sudo make installshould copy the full set of headers for the library to /usr/local/include.
I still need to check the header path for building with make (without installing).
Please check if this helps.

[Nightwalker-87]

@Crest I have checked the debian package as well, and can confirm that there are missing header files, namely:

libusb_settings.h
logging.h
md5.h
sg.h
usb.h

Also the debian package libstlink-dev should install stlink.h and stm32.h to

 /usr/include/stlink/stlink.h
 /usr/include/stlink/stm32.h

which is not the case currently.

[Nightwalker-87]

Should have been addressed in 31b1fa1.
@Ant-ON Can you help closing this ticket? I think this should be easy to solve. I only need some feedback.

[Ant-ON]

@Nightwalker-87 I compiled and installed the developer branch. All header files installed correctly:

anton@pc:~/test$ du -a .
...
4	./include/stlink/md5.h
8	./include/stlink/reg.h
4	./include/stlink/sg.h
4	./include/stlink/helper.h
4	./include/stlink/backend.h
4	./include/stlink/version.h
8	./include/stlink/chipid.h
4	./include/stlink/stm32.h
4	./include/stlink/usb.h
4	./include/stlink/logging.h
4	./include/stlink/flash_loader.h
12	./include/stlink/stlink.h
4	./include/stlink/libusb_settings.h
4	./include/stlink/commands.h
...

Also checked the compilation of the simplest application which used the library. All is well.

anton@pc:~/test$ gcc -O0 -g -I~/test/include -I~/test/include/stlink -I/usr/include/libusb-1.0 -L~/test/lib -o test test.c -lstlink

test.c:

#include <stlink.h>

int main()
{
	char serial[STLINK_SERIAL_MAX_SIZE] = {};
	stlink_t *st = stlink_open_usb(UDEBUG, 1, serial, 1800);
	stlink_close(st);
	return st != NULL;
}

[Nightwalker-87]

Fixed in 31b1fa1.