Adding examples to this repo

[raphnet]

I was wondering what you would think of adding an examples/ directory to the root of the repo, where examples and demos using different devkitSMS features could be added? I notice there is no such thing, so maybe you prefer to have this elsewhere?

For instance, when contributing new features, I often make a simple program to test it but there is no good place to share it right now. I think it would make sense to have examples here, those could also be an easy starting point for new projects.

[sverx]

This is definitely a good idea. I would say good example source files are 20 to 50 lines of code but if some topic needs more lines of course it'll be more.

[raphnet]

Do you have a preference or ideas for the directory structure? Here is my suggestion:

examples/ examples/README.md : List of the examples, with short description, target system (SMS, SG1000, etc)

For complete examples that can be compiled resulting in a working ROM, I would use the following structure:

examples/name/main.c examples/name/Makefile examples/name/how-to-compile.txt (or compile.bat ?) examples/name/README.md (optional - for details, explanations or anything pertinent) examples/name/assets (optional - if needed for the example) examples/name/* (optional - other files as needed)

The makefiles could assume the required tools (sdcc, ihx2hex, makesms, assets2banks) is in the path. The how-to-compile.txt file is simply a list of commands to compile (the same the Makefile would run). I think it could be easier to understand for beginners or anyone not familiar with makefiles.

[sverx]

I wonder if it's worth having an additional folder under examples/ for the different systems, such as

examples/sms/
examples/gg/
examples/sg/

or if we could just add -gg or -sg to the example name when it's a GameGear or SG-1000 specific example.

Also SG-1000 is using a different library altogether... mmm...

I don't know, I've got to think about it. :thinking:

Maybe have separate example folders under each library directory so that the examples refer to the usage of that specific library?

SMSlib/examples/
SGlib/examples/

[raphnet]

I think adding an additional layer of folders for each system is nice, the only drawback it that it leads to some duplication. For instance, many examples will compile at least for SMS and GG. For the simple hello world example I intend to begin with, that would mean two identical files, one under sms/ and the other under gg/... But that's not the end of the world.

As for placing examples under the library directory, I thought about it but I did not like it, as this makes less sense for examples also using other libraries, such as PSGlib. Because depending on the subject, you then have to think where the example fits best.

For instance, a basic SMS/GG playback example for PSGlib could fit well under PSGlib/ I guess, but then imagine a more complex example demonstrating the use of the vblank hook to play music in the background. Would this go under SMSlib since the focus is not really PSGlib? Also consider an example using assets2banks demonstrating how to handle a multi-bank resource. Should this be considered an SMSlib example? Or should it live in an assets2banks/examples directory?

With an examples/ directory at the root, no need to think about all this. I guess one way to see it is that this is going to be a collection of devkitSMS examples rather than SMSlib/PSGlib examples, which is why the examples/ directory would belong to the root of the project.

And as a user discovering devkitSMS, I imagine I would prefer all examples in one place, so I can see quickly what's available.

[sverx]

What if we start simple with an example folder with examples in there and naming them with some suffix in case it's a system specific example and no suffix if the example is for both sms and gg? Say helloworld-sms, helloworld-gg, helloworld-sg for example, but then only sprites and sprites-sg.

Also, I hate hello world examples where there's just one printf. It is a terrible example in general, and worse on such systems as the SMS. I think we should either avoid hello world at all or have a background image loaded up which says that, which would in turn be in fact a background example instead, so one should call it background to have a proper name.

[sverx]

I'm reviving this issue because I'm (trying to) add more examples to the repository, but I'm not very good at makefile-fu :roll_eyes:

Any idea about how to add the call to assets2banks to process the assets in the assets folder? Of course it will generate .h and .rel file(s) and this needs to be done before the sources are compiled by SDCC.

Anyway I know you can instruct make to run a recipe only once even if it process multiple files using the &: syntax as I do in one of my programs:

assets2banks.h bank6.rel bank7.rel bank8.rel bank9.rel bank10.rel &: ./assets/*
	$(ASSETS2BANKS) assets --firstbank=6 --compile --singleheader

but I don't know how to generalize this recipe (if it's possible) in the way you did with the two examples already in the repository.

Can you help me? :sweat_smile: