Some observations - some proposed fixes

TG9541 commented 5 years ago

Hi Georg,

I cloned 123b622 and tried to follow the instructions here. I'd like to share some of my observations, some problems I ran into, and propose some improvements with respect to test automation.

Tools installation

As all the required tools were already present on my Ubuntu 16.04 x64 machine (SDCC 3.6.0, stm8flash, default Python 2.7...), and I decided to skip the SPL installation for now.

There is, however no indication, that the project requires Python 3 (a subset of the scripts have a #!/usr/bin/python3 header).

It worked for me but some more clarity (and consistency) wouldn't hurt :-)

Getting started

In the fist bullet point, it's not really clear where to copy a suitable example, nor what such a suitable example is, and thus I tried Basic_Project in the repo root folder with the following result:

thomas@w500:~/source/stm8s/STM8_templates/Basic_Project$ ./build_upload.py 
Traceback (most recent call last):
  File "./build_upload.py", line 42, in <module>
    import misc
ImportError: No module named misc

I tried a different example (ADC_Measure) with the same result.

Browsing the docs once more didn't help, so I stopped here.

Through the back door

I instead turned to the script ./Projects/build_all_projects.py and ran it. It was a nice surprise that the first examples compiled normally - until the notorious SPL made itself noticed:

compile ./STM8_StdPeriphLib_Examples/Basic_Project ... In file included from ./SPL.c:13:
./stm8s_conf.h:22:19: fatal error: stm8s.h: No such file or directory
compilation terminated.

I then got the SPL from https://github.com/bschwand/STM8-SPL-SDCC (thanks for providing it!), and tried to figure out what to copy to ./Library/.

I guess that in tool-installation the instruction should be "copy the content of SPL folder Libraries/STM8S_StdPeriph_Driver/" instead of "Library" .

A patched SPL library is now available on GitHub, and maybe it would be easier to integrate into the STM8_templates directly? As the saying goes: In for a penny, in for a pound :-)

Why ask the user to "press return" if the build exits anyway?

Indeed why do I need to press return twice...

press return ...

Which is surprising since build_all_projects.py uses the parameter skippause when calling build_upload.py. Also build_all_projects.py doesn't provide a skippause option (the conditional pause block is if True:.

Even if it did, the input request comes from Tools/misc.py and appears to be unconditional. I usually try to run my stuff in a Continuous Integration system, and keyboard pixies, e.g. inside Travis-CI, require an awful lot of training on the job ;-) .

Runs on my machine...

After copying in the SPL files, compilation stopped when compiling Basic_Project:

compile ./STM8_StdPeriphLib_Examples/Basic_Project ... SPL.c:46: warning 85: in function assert_failed unreferenced function argument : 'file'
SPL.c:46: warning 85: in function assert_failed unreferenced function argument : 'line'

?ASlink-Warning-Undefined Global '_GPIO_Init' referenced by module 'SPL'

?ASlink-Warning-Undefined Global '_GPIO_WriteReverse' referenced by module 'SPL'

?ASlink-Warning-Undefined Global '_GPIO_WriteHigh' referenced by module 'SPL'
make: *** [output/main.ihx] Error 1

I decided to hide the folder and look into the problem later.

Next was a similar problem in Minimal-C. It got the same treatment.

compile ./STM8_StdPeriphLib_Examples/Minimal-C ... SPL.c:52: warning 85: in function assert_failed unreferenced function argument : 'file'
SPL.c:52: warning 85: in function assert_failed unreferenced function argument : 'line'

?ASlink-Warning-Undefined Global '_GPIO_Init' referenced by module 'SPL'

?ASlink-Warning-Undefined Global '_GPIO_WriteLow' referenced by module 'SPL'

?ASlink-Warning-Undefined Global '_CLK_HSIPrescalerConfig' referenced by module 'SPL'

?ASlink-Warning-Undefined Global '_GPIO_WriteHigh' referenced by module 'SPL'
make: *** [output/main.ihx] Error 1

Everything else compiled (great!), and I made the folders visible again, and ran build_all_projects.py again.

To my surprise I got no error this time! The error returned after running clean_all_projects.py first, and the observed effect is reproducible.

One shouldn't jump to conclusions, and always be careful not to infer the rule from an observation, but it might be the case that both projects depend on an obscure something that's produced by some project later in the compile sequence.

Finally...

I know that building frameworks is hard (people find the most absurd ways to use them), and that's why basic smoke tests should be automated with a reference tool installation.

If you're interested I can contribute a Docker based Travis-CI setup that does basic QA chores. @larsbrinkhoff once did that for my project, and it was the best thing that ever happened to it.

This said, I hope it won't be long until your Christmas vacation :-)

Kind regards, Thomas

gicking commented 5 years ago

hi Thomas,

thanks a lot for this very thorough comment - though it points out a lot of shortcomings from my side. Unfortunately it's been quite some time that I've been working on this project, so I don't really know where to start...

Anyway, I somewhat lost interest in STM8_templates because I am now involved (a bit) in the sduino project, which aims at integrating the STM8 via SDCC into the Arduino toolchain. It is still work in progress, but Michael Mayer has done a great job of making STM8 programming easy. E.g. no hassle with cryptic Python build-scripts or missing library paths... ;-) Maybe you want to take a look at sduino instead...?

Some more remarks on your comments:

I decided to publish patches only because SPL is not 100% OSS (see this discussion). Maybe I'm just paranoid but I don't need legal issues... So patchfile it is, sorry!
the basis of STM8_templates is a custom peripheral header stm8s.h. Creating and debugging it was very painstaking! Now I realized that I would need individual headers for the other variants like STM8L. On the other hand the SPLs already provide them for all STM8 variants (+ corresponding functions). Kind of a motivation killer...
IMHO the main issue with SPL is that code using it becomes huge. Now both sduino and this project found a way to split the SPL into individual functions prior to compiling. With this the SPL overhead becomes quite small. With that my main motivation to create a lean framework for STM8 is void.

All in all I have the feeling that STM8_templates is a dead horse. The effort to make it as flexible as the various SPLs, and as easy to use as sduino, is just too big. I rather spend my time on other projects.

Maybe I should point this out clearly on the repo homepage to warn people off...!? In any case sorry for the time you wasted due to my limited Python skills and poor testing! And thanks again for your thorough comments!!

Regards, Georg

gicking commented 5 years ago

PS: what's that "Travis-CI" you mentioned...?

TG9541 commented 5 years ago

Hi Georg,

There is nothing wrong with losing interest in a project that's not fun anymore. Putting a "sorry, we're closed" sign there would make things clear, though :-)

I had been looking for an STM8 framework for testing an idea that recently received some interest from a team member. Of course, sduino also fits the bill!

I'm aware of the sad state of ST's SPL, but hey, that's a company with at least 100 departments and, likely, no less than 8 levels of hierarchy. It's maybe unavoidable that common sense gets bored and walks away somewhere between the 2nd and the 7th level. On the other hand, the marketing department guys spend millions to look cool nonetheless, and they won't do anything that might discourage the hobby crowd. They even managed to come up with the hyperbole freedom terms ;-)

Travis-CI is a continuous integration system with very good GitHub integration that's free to use for Open Source projects. They supports Docker containers, and the runs are reasonably fast. For sduino, I'm almost sure, it would be a good choice.

Kind regards, Thomas

gicking commented 5 years ago

hi Thomas,

ad 1) Done. Sorry again for the inconvenience! It had simply slipped my mind :-(

ad 3) I know exactly what you mean - Dilbert in action... ;-) But especially because of that I don't assume common sense but rather play safe and publish patches only.

ad 4) That looks very promising indeed. Maybe I will come back to you on that if I may...?

Good luck with point 2 and have a Merry Christmas! Ho ho ho... Georg

TG9541 commented 5 years ago

Hi Georg,

ad 4) I'd happy to get you started. Just open a ticket in the sduino repo and post it here.

Merry Christmas, too! /Thomas

PS: please check your Connect invites!

gicking / STM8_templates

Some observations - some proposed fixes #6