A first example to get the ball rolling

[raphnet]

As discussed in issue #37, I know you do not like Hello World examples, but I do not agree that they are useless. Not only people usually expect one, but compiling for SMS using SDCC is different that what most people are fimilar with (i.e. it's not just gcc on Linux) and there are extra steps specific to the SMS such as converting the ihx to a .sms. So this is a nice how-to-compile example.

The example does teach the existence of the auto text renderer and how to write on the screen (using the new SMS_printstring by the way), but the way I see it the main goal here really is showing how to compile and do something minimal without any additional complexity in the way. I mean, as you suggested, using a background image instead of text would be good, and I intend to do so next. But I would not like to merely include a .c with a large data array. I would also want to show how the original png was converted using png2tile, how assets2banks was run, probably all from the Makefile. I think all this would distract from the essential, that is how to compile and quickly get something running.

[sverx]

I do agree the first example has to be minimal, and that the important part is to make sure you can go all the way from the C source to the binary sms ROM file, but I still think this is an example better suited for text rendering.

On the other hand, I hardly can imagine some very simple example apart from something like zeroing the whole VRAM and setting the BG color to some blue or whatever. I mean, this would surely be enough to tell if the whole thing works but I understand it would be way less satisfactory.

I don't know. Probably we could keep this as an 'Hello World'/'Text Render' example and create what I just said as a very basic bare minimum example and give it an appropriate name such as 'first test' - if you can compile this you're good to go.

[raphnet]

Ok, I created a "first test" example which sets a blue background, for SMS and GG.

[sverx]

This is perfect! ❤️
Let's add a screenshot to the Hello World/Text Render example and I'll merge it.

Also, can you explain me the note on the makefile? The one about the .PHONY line... 🤔

[raphnet]

The .PHONY directive forces a target to run every time make is invoked. Here is a demonstration of the problem this is working around.

First, let's say everything is fine. Your project compiles from A to Z without errors, i.e. everything compiles you link your .RELs, get a .ihx, then convert the ihx to SMS. Let's look at the file timestamps:

-rw-r--r-- 1 raph raph 12144 Sep  8 18:50 hello.ihx
-rw-r--r-- 1 raph raph 32768 Sep  8 18:50 hello.sms
-rw-r--r-- 1 raph raph   892 Sep  8 18:48 main.c

Then you make a change to your main.c which results in a linking error, for instance, an undefined symbol. To do it on purpose, add extern int aaa; and assign something to this var somewhere. Here is what happens:

$ make
sdcc -o hello.ihx --no-std-crt0 --data-loc 0xC000 ../..//crt0/crt0_sms.rel ../..//SMSlib/src/SMSlib.lib       main.rel

?ASlink-Warning-Undefined Global '_aaa' referenced by module 'main'
make: *** [Makefile:27: hello.ihx] Error 1

Ok, so this last sdcc execution is supposed to generate hello.ihx out of the provided rels. But the extern aaa symbol we declared on purpose here does not exist. The sdcc process ends with a non-zero value, make catches the errors and stops there.

Let's look at the file timestamps again:

-rw-r--r-- 1 raph raph 12156 Sep  8 18:54 hello.ihx
-rw-r--r-- 1 raph raph 32768 Sep  8 18:50 hello.sms
-rw-r--r-- 1 raph raph   913 Sep  8 18:54 main.c

Oh? hello.ihx exists and has a new timestamp despite the error (sdcc returned non-zero)! The .sms file is still old, since make stopped after the error. But then, if we type make again, make only sees that only hello.sms is out of date and runs the target that converts the .ihx to .sms.

$ make
sdcc -mz80 -I../..//SMSlib/src --peep-file ../..//SMSlib/src/peep-rules.txt -c main.c
sdcc -o hello.ihx --no-std-crt0 --data-loc 0xC000 ../..//crt0/crt0_sms.rel ../..//SMSlib/src/SMSlib.lib       main.rel

?ASlink-Warning-Undefined Global '_aaa' referenced by module 'main'
make: *** [Makefile:27: hello.ihx] Error 1

$ make  # Let's run it again!
ihx2sms hello.ihx hello.sms
*** sverx's ihx2sms converter ***
Info: 5231 bytes used/32768 total [15.96%] - size of output ROM is 32 KB
Info: release date in SDSC header updated
Info: SEGA header found, checksum updated

$ make  # Let's run it once again... 
make: Nothing to be done for 'all'.

See how the last time make is telling you everything is fine and done, yet the .sms file (that Emulicious reloads automatically in my setup) is old and holds none of the changes I think I made? Sure, to get there, you have to miss the error the first time make ran, but the above is not the behaviour I want and expect when I type make. If a step fails, I want the build to fail every time I type make. In real life, link errors happens when you do not type a function name correct or are making changes to a library.. I got bitten by this a few times, hence this workaround.

[sverx]

I see. I got this issues once or twice too and I thought I could solve by having the linking and conversion phase in a single recipe so to avoid that the conversion would take place without the linking, but it seems to me your approach is way better!

[sverx]

Reviving this discussion because I just found out that make supports
.DELETE_ON_ERROR

so instead of that .PHONY I tried putting
.DELETE_ON_ERROR: $(PROGNAME).ihx $(PROGNAME).sms

and now if the linking phase fails (or if the ihx2sms/makesms tool fail) you get the ihx and sms file removed.

When everything compiles/links/converts fine, the ihx file is retained too so next make call simply informs that there's nothing to be done.

It seems to work fine but I wonder if there's something I'm overlooking here? 🤔