Git cheatsheet

Using Git to develop RISC OS

The source code to RISC OS in held in a version control system called Git, making it easy to see who changed what and why. Everyone can take a look around by going to the ROOL gitlab. To be able to make edits to the code you’ll first need to create an account then log in.

The remainder of this page describes how to work with Git to propose changes to RISC OS, if you only want to browse, go exploring!

Using Git as a developer

Introduction

At present there’s no mature Git client that runs on RISC OS directly, so the step involving Git requires the client to be run on another computer such as a Linux, Windows or Mac. Note that this doesn’t necessarily need to be a traditional computer: you could use a NAS or a Raspberry Pi running Raspbian, for example.

For very simple edits, you can even use the GitLab web interface on a supported browser. However, because this would mean you’ve not tested the change on RISC OS, this isn’t a recommended method of working.

To compile the sources you’ll need the Desktop Development Environment (DDE) and a means of running that on RISC OS itself. You can do this using an emulator, in which case you need to do your Git operations within a directory that is visible from the emulator. Otherwise, you need to use a file sharing protocol (such as SMB or NFS) to enable files to be transferred to and from your RISC OS machine. A recent native RISC OS machine will typically be many times faster than an emulator, so is the preferred option if you will be doing repeated incremental builds.

Organisation of the sources

The sources are arranged in a hierarchy:

Also at the top level are some non-source files in supporting roles:

For some of the simpler components, the DDE contains everything you need to build the component in isolation. In this case, you can fetch just that one component. If you know the name of the component you would like to work on, but don’t know where to find it, you can go to the Explore projects page and use the “Filter by name” box to search for it. If you’re totally lost, the build system itself looks up the location of a component in the ModuleDB which will direct you where to go beneath the top level of RiscOS.

A product, such as a ROM image or a disc image, comprises multiple components and we’ve organised these into super-projects available under the Products hierarchy. These refer to whichever components are needed to complete the build. For most intents and purposes, you can interact with each of these components in the same way and using the same tools as any other Git repository.

Basic operations

Use the following cheat sheet as a reminder of how to perform the most common operations.

• Workflow via Linux, the command line, and NFS
  • Get sources to a single component
  • Getting the latest sources to an entire product to build on RISC OS
  • Getting the source to a particular version of a build
  • Viewing the history of my local source tree
  • Local setup before you start to make changes
  • Recording your changes locally
  • Updating your clone with the latest version
  • Submit changes for review
  • What happens next?
• Workflow via Windows, TortoiseGit, and SMB
  • Get sources to a single component
  • Getting the latest sources to an entire product to build on RISC OS
  • Getting the source to a particular version of a build
  • Viewing the history of my local source tree
  • Local setup before you start to make changes
  • Recording your changes locally
  • Updating your clone with the latest version
  • Submit changes for review
  • What happens next?
• More advanced topics
  • Working with superprojects
  • Tips and tricks for pro users

Creating a completely new component

New components can originate either on another publicly visible Git server or attached to an email to the usual submissions address. Don’t worry about setting up the access permissions as we’ll map those to a standard setup used by gitlab which may differ from your usage. However, the following are prerequisites for ROOL to host your project in the main RISC OS source tree:

• Required
  • The provenance of the software must be clear, and must not breach any copyright or trademark rules
  • Source files should have boilerplate copyright statements or SPDX markers prefixed (generally these are omitted from resource files such as !Run obey files)
  • All system-wide unique values such as error blocks and application names must be allocated
• Preferred
  • Use the shared makefile fragments for standard layout component types: modules, applications, HALs, utilities, libraries
  • The change history should have the change history for as many previous releases as possible, the history often has useful insights that are lost if only the latest version is provided
• Optional
  • A top level LICENCE file is present in the repository, if missing we’ll add one based on a survey of the component
  • A top level gitattributes and gitignore control file, if missing we’ll generate these based on a survey of the component
  • Provide a 64×64 pixel PNG to use as the component icon, if missing a generic icon may be assigned or none at all
  • Add the new component to the Module Database and Products list, if missing we will seek guidance of where it should go