[Tasks]: Basics of coding on RISC OS

[pzaino]

Contact Details (optional)

No response

Background

After "Getting the code" the next logical milestone should be introducing the "differences" with other environment when coding on RISC OS.

At the last coding meeting we thought of presenting a set of coding micro-projects (all with the exact same theme, just implemented in different programming languages) which should focus on the specific bits that make coding on RISC OS different than just doing the exact same thing on a different Operating System.

Here are the requirements:

• Program should be single task, let's avoid discussing the WIMP and ToolBox at this first set.
• Program fuctionalities should be
  • Turn keyboard caps lock on and off
  • Write a message on the screen
  • As an extension, turn an LED on and off on the GPIO (or equivalent)

Objectives of this excercise are:

• Show the differences between RISC OS File System naming convetions: The "." vs "/" on UnixLike for example, the absence of file extension (we use file types), etc.
• Show the "Drag'N'Drop" nature of the OS: For instance, on RO we do not usually start from requesting the Filer to create an empty file and then edit it, we actually open an editor and start writing our code and then we save it without the need to browse a file system from within the editor.
• Show the use of SWI calls (arguably the RISC OS API): this because in RO we do not have the same level of abstractions that other OSes present normally. For this portion, it's important to make sure people understand they are passing values to registers, so address pointers to memory blocks should be aligned, in RO the kernel can access the application space and viceversa and all other requirements to make an SWI call as "safe" as possible.
• Show other differences of coding on RO vs on other systems: for instance, RO offers no protection from bad coding consequences.

Programming languages that we shall use for this one are:

• ARM Assembly (providing understanding of ARM Assembly doesn't mean we are promoting the use of it, it's more a way to help people understand RISC OS)
  • In ObjASM
  • In GCC GAS
  • In BBC BASIC ASM
• BBC BASIC
• ROOL DDE C
• ROOL DDE C++
• RiscLua
• Python
• GCC C
• GCC C++
• If you think we are missing some relevant languages please let me know!

Feel free to pick your favorite language, make sure you post here which one you pick, so there aren't people duplicating effort.

Please note: Your code will have to be received with an Open Source license that allow us to upload and store it in this repository for users to use and read: https://github.com/RISC-OS-Community/CodingOnRISC-OS

If possible, lets share how we are going to solve the problem, so that everyone can use a very similar approach. This may sound a bit bizzare, but the idea is to focus on the specific of coding on RISC OS, not on solving the problem in different ways. This way, when watching the series, people will focus on such differences instead of trying to understand all the different approaches we used to solve the same problem (hope this makes sense).
This has been really effective with the git series, because we where all using git clone / git add / git commit and git push, so at the end of all the videos, people were well aware of those things (repetita iuvant!), while each video showed the differences between each approach.

Requirements for each video:

• Each video should NOT be shorter than 5 minutes and should NOT be longer than 15 minutes (average length should be around 10 minutes)
• If it helps you, divide your video in multiple takes (or chapters), I'll recombine them together in a single video, no worries :)
• if you make a single take, please leave few seconds of silence between each chaper so I can add "chapter labels" when editing. 5 seconds should be enough, thx.
• video's resolution should be full HD (1080p). From the previous set of videos some people have asked if we can capture at 720p (and still have the video at 1080p), this makes fonts larger and more readable on mobile devices (at this time we have a rate of views from mobile devices of ~ 30%)
• Ideally each video should be provided in mp4 format, but I can also translate multiple formats, just make sure you do not compress your video(s) too much to make them lose video and audio quality. If in doubt, ask me if I can use a specific format or not, thx.
• Make sure you talk close enough to your microphone (usually few cm from the mic, between 3 to 12cm from the mic) and, if you do multiple takes, that the microphone is always in the same position, so the sound of your voice will be as consistent as possible, thank you :) - don't worry if the sound may feel too low, I'll fix that during editing.
• Make sure the audio is not distorted (aka too loud), this is something I can't fix, so low audio volume is better than too high volume.
• It's totally ok to use emulators for a video, if you wish to also add the GPIO extended goal, then I would recommend to focus on the Raspberry Pi which is the most popular RISC OS platform at the moment.
• It's totally ok to use old releases of RISC OS (no need to focus only on RO 5, all RO releases are welcome!)
• On the YouTube channel we release videos with the CC LIcense, so please make sure you understand this and accept it before you submit your video, thank you.

Info on the next meeting here: https://github.com/RISC-OS-Community/CodingOnRISC-OS/blob/main/doc/RISCOSCodingMeetingsSchedule.md

Info on the collected requirements here: https://github.com/RISC-OS-Community/CodingOnRISC-OS/blob/main/doc/RISCOSCodingMeetingsIdeas.md

As always, if I have forgot something, if I made any mistakes, if you have ideas for improvements or suggestions, please let me know and I'll update this post, thank you!

• Paolo

Definition of Done

• Sending me a video in mp4, mov or other standard format with the requirements at Requirements for each video:
• All the videos cover the requirements at "Objectives of this excercise are:"
• Videos must be sent before the 1st of March 2023 (this is because all my edits have to be ready and published by the 4th of March morning 2023)
• I have received your source code, with an appropriate license for publication
• We had fun :)

Code of Conduct

• I agree to follow this project's Code of Conduct

[GavinWraith]

Dear Paolo I have to confess that I have not made any videos. That is because I have lacked the equipment; in particular I have no microphone. However, I have just ordered a tiny USB microphone from Amazon, which I am hoping will work with my Pinebook+Manjaro machine. I am very ignorant about the whole business of videos, as you will infer from my naive questions. What is the file-/mime-type of video files? Can one interrupt recording temporarily and then continue later? Can one split a video into pieces, and splice in or remove sections, and then join the pieces together? Or is some super-whizz-bang editing software necessary? I guess most people use their mobile phones to make videos. My mobile phone is a Doro, Swedish, very cheap but designed for old folk; it has buttons and no hand gestures. I have not even succeeded in phoning home from the local supermarket, let alone get a taxi. I can use it to take photographs, but I cannot transfer them out of the device. I can pair it by bluetooth to my Linux machine but attempts to make a transfer of files just gives an error message saying that the requisite software is not present. There is no USB socket. So my mobile phone is pretty useless. Maybe I am too old for that particular techno-revolution anyway. I would like to contribute to the RISC OS Coding project, but I will need to tool up first. Best wishes

…

-- Gavin

[rps102]

ARM Assembly (providing understanding of ARM Assembly doesn't mean we are promoting the use of it, it's more a way to help people understand RISC OS)

It occurred to me that this could be done as ARM assembly (in ObjAsm or gas, perhaps tacked onto the end of the DDE and GCC ones) and also with the inline assembler in BASIC (perhaps tacked onto the end of the BASIC one)

The inline assembler in BASIC has the advantage that people can dip their toes in using something built into the OS and jog a distant memory to anyone familiar and returning to the fold from a BBC Micro background.

[pzaino]

@GavinWraith ,

Hey Gavin! :)

What is the file-/mime-type of video files?

Ideally, each video should be in mp4 format (that still has great quality and the file is relatively small to transfer). However, most standard formats are fine, here I have a recordign studio and have some hardware that can convert formats really fast.

These are the most common formats: mp4, mov, m2t, mkv, avi, wmv, mxf, m4f, xvid, asf, dv, mpeg, ogv, dvix, 3gp, ts, mts, trp, mpg, flv, f4v, mtv, and dpg (there are others, but not as common). I can read and write them all, so make sure you pick the best one to preserve best quality for your video.

Can one interrupt recording temporarily and then continue later?

Absolutely :) - That is what I meantioned as making a video in chapters/subchapters. The only thing you should pay attention to when you record this way is make sure you take note of the position of your microphone on the first recording and put the microphone on the other recordings in the same position (a selfy is good enough if you have a mic on an headset). This ensure best possible consistency towards your audio. I can fix most audio issues, but the more audio issues the longer it takes me to prepare/edit your video, so the consistency with the mic position helps me a lot, thanks.

Can one split a video into pieces, and splice in or remove sections, and then join the pieces together?

Yes, you can send me the "pieces", I'll rejoin them together. This is because I have all the required tools to add transitions, subchapters, blend it audio etc.

On the first set of videos we produced, there wasn't enough space between sections, I think only Sprow recorded the video with enough "space" between sections. Make sure to leave roughly 5 seconds of silence at the beginning and at the end of a chapter, this because on instructional videos we wish to add a "label" at the beginning of a chapter, to help the viewer to understand where we are and what we are goign to talk about. It's not a must have, but it helps.

Or is some super-whizz-bang editing software necessary?

Not on your side, no. All you have to do is record the "raw material" (aka your screen), I'll have the super-whizz-bang editing software to produce what you have probably seen already on the channel, so no worries at all, leave that part to me.

What is truly important on your side is to focus on producing material that helps people understanding the matter at hand, that is really really important. I do not have to tell you how to teach ahaha I know youa re a wizz at that!

If you have time, it would also help me to have a text file of your script (what you're saying in your video), I use those to produce the subtitles for hearing impaired people, international audience and also translate them to have subtitles in multiple languages (I am still working on the scripts from previous wave of videos)

I would like to contribute to the RISC OS Coding project, but I will need to tool up first.

You're more than welcome! And thanks for asking. So, if you have a Linux system I suggest to use that to record your video. You can use RPCEmu emulator to run RISC OS on it.

If you need to gear up and it will take time, then you can still help me with RiscLua, we can work out the code together and I could record the video for you (as long as you do not mind my Italian accent!). There is going to be plenty of opportunities for RiscLua videos, so take your time to gear up properly.

Hope this helps my friend, also don't forget to check out this link for updates on this chat:

#23

Cheers!

[pzaino]

@rps102

It occurred to me that this could be done as ARM assembly (in ObjAsm or gas, perhaps tacked onto the end of the DDE and GCC ones) and also with the inline assembler in BASIC (perhaps tacked onto the end of the BASIC one)

Great catch! I completely forgot about this! Thanks a lot and yes, we should show all the various ways to do ASM on RO.

The inline assembler in BASIC has the advantage that people can dip their toes in using something built into the OS and jog a distant memory to anyone familiar and returning to the fold from a BBC Micro background.

Totally agree, so added the 3 major players to the list, thanks for pointing this out.

I think we should probably make 3 separate videos (one per each assembler), so I can label the videos proper for the specific ASM to have a good indexing and easy to find way for people interested in just one or the other (as you've mentioned people with BBC Micro background, may which to check the BBC BASIC Assembler the most probably)

Thanks!

[GavinWraith]

On Mon, 23 Jan 2023 04:53:48 -0800 Paolo Fabio Zaino ***@***.***> wrote: These are the most common formats: mp4, mov, m2t, mkv, avi, wmv, mxf, m4f, xvid, asf, dv, mpeg, ogv, dvix, 3gp, ts, mts, trp, mpg, flv, f4v, mtv, and dpg (there are others, but not as common). I can read and write them all, so make sure you pick the best one to preserve best quality for your video.

Thanks for the info and the offer to edit videos. My usb microphone arrived and seems to work. I attach a tiny RiscLua program for setting capslock off and on. Does this fit what you were after? The PRMs talk of led lights, but I suppose that may no longer be of relevance these days, as whether there are any led lights at all depends on what keyboards folk are using.

…

-- Gavin

[gerph]

I attach a tiny RiscLua program for setting capslock off and on. Does this fit what you were after? The PRMs talk of led lights, but I suppose that may no longer be of relevance these days, as whether there are any led lights at all depends on what keyboards folk are using.

The attachment didn't make it to GitHub, unfortunately. It made me try to remember how to change the LEDs, though, as it's not something that I knew off the top of my head.

Good luck making some videos, Gavin - it's actually kinda fun.

Something I find very useful in making the videos - other than having a microphone and a way to record the screen - is knowing what I'm going to say is really useful. I usually have that planned out and written down beforehand as my script, so that I can just read off it as I go. Invariably I find that I've made sentences too long, or written in a way that is impossible to read out, so I need to make a couple of runs through. What bothered me at first was that my results never sounded as polished as other people - and that's both practice, and picking out the good takes :-)

[pzaino]

I need to also add these two requirements:

1. Videos will be distributed with CC license
2. Programs examples will be uploaded to the "CodingOnRISCOS" repository here: https://github.com/RISC-OS-Community/CodingOnRISC-OS

So please make sure your code has an open source license, I am happy with whatever you guys wish to use as long as it doesn't send me to jail! 🤣

[edit]
ok added!
[/edit]

[pzaino]

quick note: @GavinWraith had a great idea and added a comment to his RiscLua script with reference to the relevant pages on the PRM, maybe we should all do the same?

  -- PRM 1-883
  local _, status = sys (6, 202, update, mask)

Thanks

[gerph]

It may help if people included the chapter name as well, as the electronic versions won't include the same page numbers.

The page numbers in any electronic manuals in the future will almost certainly not line up. I do not remember if I ever made my conversion of the PRMs to StrongHelp available, but I suspect they were relatively private as I never had the rights to them, so whilst that might probably help, it probably isn't as useful.

[pzaino]

quick update:

As mentioned above, I have received RiscLua code for the video challenge from Gavin.

Today, I also received BBC BASIC code from Andrew Conroy, which has a lot of info on using the GPIO, so I'll shrink it down to the specifics of the code challenge.

I am thinking of creating submodules for this repository to store all the code examples, I know that submodules may not be the best approach, but they would help to avoid a user to pull down all possible code examples for all programming languages - I am also preparing old Acorn C code examples fixed (for ROOL DDE) and made a bit agnostic (build with GCC) for the ToolBox etc., from the years of the RiscCafe, Dev CDs etc. -

So, the question is: Do we want to use a different way to upload all the code examples? Or is submodules (one module per each programming language for example) ok for everyone?

Thanks!

[gerph]

Depends on what you're trying to do... if you're trying to collect resources which can be referenced by people, rather than something explicitly that they check out, then using a repository with a README that gives a list of examples might be useful, in the style of the 'Awesome XXXX' lists - but these examples are only really useful together with the videos, so you would want to have them linked appropriately.

Using submodules isn't a big deal for people that are comfortable with Git, but most won't be and even those that are may have strong objections to using submodules (I'm not one of those people - they have a place and are great). However, in this instance, using a submodule may not be ideal because a submodule reference is to a specific hash, which means that you'll always references that point in time, unless you keep updating the repository when others update their code - everyone would have to keep telling you 'I've updated my repo, can you update your reference'.

In this case, there is no /need/ to reference all the repositories as a checkout-able source (in my opinion) so I don't think that submodules would be quite right.

Remember that there are other resources available, which provide pure example code - my own riscos-examples repository has many GPIO examples which have inline comments to explain things, but aren't examined in more detail. Rosetta Code has similar examples that show how certain things can be done as comparisons between different languages, but in some cases that might be useful (and there should be more BBC BASIC examples there, obviously :-) ). So if you were doing just a plain 'awesome list' that might be a way to do it.

So really... I guess I don't have strong opinions, but I'm not convinced by the submodule way of linking to the code. I guess it will pay to think about how the user will find the video, and then where they'll go, or how they'll get from the sources to find other related examples. And that, I'm really not sure of.

[pzaino]

@gerph

Thanks fo ryour feedback!

Remember that there are other resources available, which provide pure example code - my own riscos-examples

Thanks a lot, I checked it out and saw they are all BBC BASIC examples, so (if it's ok), will add the link to the 'Awesome XXXX' like list we have here :)

P.S. I asked people to let me know of all their resources, so to be able to link them here. I renew my request also on this post, if that helps!

Depends on what you're trying to do... if you're trying to collect resources which can be referenced by people, rather than something explicitly that they check out, then using a repository with a README that gives a list of examples might be useful, in the style of the 'Awesome XXXX' lists

Yes, this is the idea for the Doc section, and I already started to collect links to resources, however I also wish to provide code examples to be pulled via git.

I have permissions to publish all the old Acorn's C and ASM examples, which I have mostly converted for RO 5 and modern DDE as well as for GCC (running on RO). I still need to finish converting the old ASM examples from ObjASM to GAS, but I am getting close to the first chunk of converted C ready to be published.

So, if we want to keep this repo as an 'Awesome' like resource, I'll just upload the C stuff in it's own repo and link it here as for everything else, via the documents.

I am happy with both approaches to be honest, so don't have a preference. My question was mostly on the line of, if we want to have a single repository that contains all possible knowledge, then submodules may help to avoid people downloading everything everytime they do a git clone, because they might be interested only on resources abotu a specific programming language.

So do we want separate code resources then? (again I am happy with both approaches)

[pzaino]

All,
I haven't heard anymore from anyone, so here is an update:

I have completed most of the required code (All ASM, C, C++) and have the source from Gavin for Lua. Please consider my code as a backup plane if you are too busy at the moment. So, if you still fancy to make a video for your favorite programming language please feel free, however I need the videos, because we are getting close to the meeting date and I'll need some time to fix audio, editing the videos and add head and tail to each one.

P.S. @gerph I added your BBC BASIC code repo to the "awesome"-like document (it's in the develop branch at the moment), if there is anythign you want me to change, please let me know (or just change it yourself), thank you :)

Thanks again for all your help!

[gerph]

I had meant to spend some time on this, but the last month has been a little busy with other things (testing Internet 7, other bits of Pyromaniac and other life-stuff). No way I'm going to get anything done today or tomorrow, I expect :-( Bad organisation on my part as I did want to do some bits. Sorry :-(

Glad to see you've included my examples in there. Not sure whether it's directly useful, but there's also a 'tests' repository (https://github.com/gerph/riscos-tests/), with code that exercises some of the interfaces, which people might find useful - I had hoped that some of the people working on RISC OS sources or ports might take and use some of it, or contribute useful tests, but haven't had any feedback from anyone.

[pzaino]

Not sure whether it's directly useful, but there's also a 'tests' repository

I think every code example can be useful for people, we do not know which type of knowledge a user may have or which type of problem they are trying to solve, so Thanks, I'll add that too! :)

No way I'm going to get anything done today or tomorrow

No worries, totally understand, I am late too due RISC OS Show and now a cold! Ok, it will be a set of videos with a strong Italian accent on them!🤣🤌

[pzaino]

All,
at this point submissions and corrections are closed. This thread was great and we have managed to produce more than 2 hours of videos 😍 this set is going to be amazing!

We have intros, BBC BASIC, Python, Lua, C, (proper) C++, GNU ASM and later on will upload also ObjASM and BBC BASIC ASM tutorials.

Thanks everyone for your help and time!

I will open a new issue for the next chunks of videos for everyone who's interested.
Cheers,