Maturing the NABU-LIB project.

[productiondave]

Heyo

A few of things I wanted to discuss. We can start separate topics if we need to.

1. Is it possible to start working on NABU-LIB natively with Git. At the moment, I think updates are being made by uploading files via the GitHub UI. Usually these sorts of projects run with Pull Requests and forks etc. That way we can have a development branch, main branch and tags to capture specific releases. Developers can be assured that if they pull down the tagged releases or check them out, that they will be working with stable code.

2. If we do move to a Git based development workflow, would it be possible to relocate the examples into a subfolder and to bring the library files up to the root of the repo. Something like this:

Code: Select all

/(root of repo)
   examples/
      Brick Battle
      ....
   lib/
      NABU-LIB.c
      NABU-LIB.h
      ...

This would make it very easy for new commers to navigate the code and understand where the important files are. It would also make it possible for us to add a

Code: Select all

docs 

folder with markdown documentation in future.

3. I was wondering if we might want to implement NABU-LIB as an actual library. Have a look at https://github.com/z88dk/z88dk/wiki/creating_libaries for some details I was tinkering with the idea of separating the Assembly functions into their own assembly .asm files too.

Thoughts?

[DJ Sures]

1. Is it possible to start working on NABU-LIB natively with Git. At the moment, I think updates are being made by uploading files via the GitHub UI. Usually these sorts of projects run with Pull Requests and forks etc. That way we can have a development branch, main branch and tags to capture specific releases. Developers can be assured that if they pull down the tagged releases or check them out, that they will be working with stable code.

Yeah okay - I'll need a few days to get into the github and sort it

2. If we do move to a Git based development workflow, would it be possible to relocate the examples into a subfolder and to bring the library files up to the root of the repo. Something like this:

Code: Select all

/(root of repo)
   examples/
      Brick Battle
      ....
   lib/
      NABU-LIB.c
      NABU-LIB.h
      ...

Funny that's something I keep thinking about every time I update stuff haha

3. I was wondering if we might want to implement NABU-LIB as an actual library. Have a look at https://github.com/z88dk/z88dk/wiki/creating_libaries for some details I was tinkering with the idea of separating the Assembly functions into their own assembly .asm files too.

I'm not a fan of separating the assembly for the linker because it changes the commandline considerably for new users. It also makes sense for functions with pre-fixes to be within the same location as other files (i.e VDP_ or HCCA_). And lastly, some functions have a mix of assembly and C, so where does that go

I do think the lib could benefit from being split into files based on their function. For example
- VDP.C / H
- HCCA.C/ H
- etc

[productiondave]

Okay, no rush on GitHub stuff. Most of us have these pesky day-jobs we need to keep doing.

Yeah - the repository at the moment looks like an examples project and not a library project. We need to shift the focus to, "This is a library and here are some examples" rather than "Here are a bunch of examples, and oh-by-the-way, there is a library hidden somewhere in here."

Once we have a docs section, I was wondering about putting something together on how to contribute. (DEVELOPMENT.md) or (CONTRIBUTE.md) so we have some rules laid out on what we expect from pull requests before they will be considered. I could probably benefit from a bit of guidance here too. Like how about testing... I'm not suggesting we invest load of hours into GitHub Actions and continuous integration or anything, just that the person raising a PR should include at least one example of how to test the change and some assertion that it worked for them.

If we do separate the library source into different files based on prefix, would it make sense to have a folder for source and another for headers? Like this?

Code: Select all

/src/
    vdp.c
    hcca.c
  ...
 /include/
     vdp.h
     hcca.h
     ...

That way when we compile, we can pass in the -I path/to/include and not have to specifically path the includes in our software. That would also make your examples a little more portable. A person could take your template and build it anywhere without having to edit the paths to the headers in the top of their source code.

I know that the .h and .c files can be together in the same folder, but I am just going on other conventions I have seen.

With regards to assembly in separate files: Is there much benefit to having the assembly inline? I know you talked about this in one of your videos but, I don't remember the reasoning.

I just figured, that if we add the assembly files to the compile command, they will be compiled and linked together. I have tried this with z88dk and it's fairly straight forward, but not - as you say - very beginner friendly. So perhaps I am being a bit too pedantic on how to structure a library. I am used to working with Make, and Make is designed for automating all of that stuff to the point where you stop thinking about it.

BTW - I am already loving this long-format, asynchronous channel to discuss things like this. Well done to you and Leo for getting this forum stood up.

[superbenk]

I'm not a programmer by any stretch but I deal a lot with git & build/deployment pipelines for infrastructure stuff. I really love the ideas ProductionDave is presenting here & would love to see them implemented. I do look forward to diving into the library & learning to program the Nabu so seeing the changes being recommended would make that a lot easier for me to approach.

Happy to help in any way I can (I can do documentation & GitHub Actions pretty well).

[productiondave]

Thanks Ben,

It's still early days in nabu-lib but we'll get there. Ive been thinking of the goal of NABU-LIB in terms of what I think dj intended when he created it.

I think he intends for it to facilitate an easy development pathway for people who might be starting out with the nabu and not wanting to get lost in the weeds trying to compile stuff.

I'd like to maintain that spirit as much as possible, while also maturing it a little bit. I think there are some easy cosmetic changes we can make that I've suggested.

Maybe the moto for nabu lib should be, "don't over complicate"

And just so we are aligned, I'm the first person to overcomplicate things. I'm far to much of a nerd and have been known to take a mastabtorial approach to stuff like this in the past!