Request for help in organising/releasing source code

[Richard Russell]

Sorry if this is rather off-topic for Stardot, but somebody suggested I ask here. It has long been my intention to release the source code for BBC BASIC for SDL 2.0 (BBCSDL) but I have zero experience of GitHub or similar. What's even worse is that the build process is different for each of the supported platforms (Windows, Linux, MacOS, Android, iOS) - in some cases it's a traditional makefile and in others an integrated tool like Android Studio or Xcode - and I have no idea how I can structure the project to accommodate that. There are even differences, currently, between some source files for the 32-bit and 64-bit builds!

At the moment everything is thoroughly ad-hoc and disorganised. What I'm hoping is that somebody with knowledge of this sort of thing can give advice on how I need to structure the project (even something as basic as the optimum directory hierarchy is outside my experience), help me to create the necessary makefile(s) etc. and explain how to get it all onto GitHub - or even better do it for me! There's no reward other than the satisfaction of having put the source code of BBCSDL into the public domain.

I know it's a lot to ask, so I'll understand if nobody feels able to make this degree of commitment to a project that isn't theirs. If you can help, be gentle with me: you will be amazed at just how little I understand about this aspect of software engineering.

[colonel32]

Hi Richard. My immediate impulse was to offer to help, as I use github and other source control systems, and have set up projects from scratch before. But I realise I don't have answers to some of the issues you mention. In particular I don't have much cross-platform experience, and don't really understand makefiles! In short, you may well get a better offer, but I'm happy to do what I can, in the longer term as well as short term.

Regarding being off topic, I am certain discussing such matters here is win/win for stardot, just as discussing your BASICs is. We all find it interesting, and we all learn things every day from reading intelligent discussions peripherally related to whatever our core interests are.

[danielj]

Very much not off-topic (you might notice we very rarely say anything is )

[Richard Russell]

I don't have much cross-platform experience

That is the most tricky aspect for me, yet I can't help thinking it's a common requirement these days. Anybody who has written an app for both Android and iOS must have had to resolve the issue of maintaining both the common features (e.g. source files) and the differences (e.g. build environments) in a version-controlled context.

I'm happy to do what I can, in the longer term as well as short term.

Thank you.

[richardtoohey]

Can't offer particularly relevant advice but maybe it doesn't matter too much about getting it right first time?

Create a scratch project or two in GitHub and try a few things. Don't think anyone will mind and if they do to them.

So maybe don't use any project names you'd want for the ideal repository.

I just have visions of there being a lot of going around (and around) trying to figure out the best way ... and maybe trial-and-error is going to be a big part of it.

Maybe you start with

tempbbcsdl/android
tempbbcsdl/ios
tempbbcsdl/macosx
tempbbcsdl/windows
tempbbcsdl/linux

and so on.

In each "folder" is the complete code & build instructions for that platform.

That way (a) your code is available and safe and (b) people who can be more helpful than me can see exactly what they are dealing with and (hopefully) help you move from that layout to a better one.

I appreciate that's doesn't tick the proper version control + cross-building aspects of what you are after - but at least it will be a step towards some sort of organisation and sharing.

[sirmorris]

+1 to that. Baby steps.

Commit in what you have, as it is, and learn about how the system works. Especially branching. Branches don't cost anything and are perfect for experimenting. Keep master clean/working at all times. Work in a branch until it's looking how you want it to then merge that back to master. Commit little and often. If a branch goes horribly wrong you can blow it away and start again.

The structure of the project is usually related what you want to achieve with it. You've said that you want to structure your project but not why. Work backward from your end goal. Is it

* to look pretty
* to be able to build all targets with one command
* to share code between targets
* save for posterity
* purely to give the world access

?

If it's the last case then just provide instructions - let the world worry about how to proceed

[dhg2]

I would suggest that you simply pack up your source code into a zip archive, and make it available that way. (That's what I would do, since I've never been able to get used to git/github)
Then you could ask colonel32 to take those files and set up the github repository for you.

[davidb]

I meant to post this yesterday but apparently didn't hit the Submit button.

I can't really tell you what the "best practice" is. However, it would be worth identifying files or components that are common to different platforms and either group them together in a repository or create a repository specifically for those files.

There's nothing wrong with putting build scripts and similar things into a repository alongside the source code and keep it all in version control together. Where people start to get fussy is when build products are also kept in version control. The same can be said of build environments if those are, for example, huge SDKs.

So, for example, Makefiles are usually seen as OK if they are written by hand, but not if they were generated by another tool, although I have seen some projects include default Makefiles for the convenience of users.

If you are worried about dropping the lot onto GitHub (or another repository hosting site) and being judged by strangers then it's OK to discuss how you might reorganise things before you do that. Just remember that everyone has their own view about how things should be organised and that you need to find what works for you.

[Coeus]

Richard, I don't have the experience of something that has that many platforms. My recent experience is with B-Em which builds on Windows and on POSIX-like systems including Linux. Building for each platform is possible from a single repository. I have delegated as much of the platform dependence to the Allegro library as possible, as I imagine you have done with SDL, and that only leaves one completely platform-specific source code file for each platform. The source is therefore all on one directory, there is a Windows-specific Makefile that includes the right set of modules for the Windows version and a GNU autotools generated Makefile that includes the right set of modules for the Linux build. The Windows-specific Makefile and the GNU autoconf input files that are transformed into the Makefile for Linux are all in the repository and version controlled.

When working with Makefiles I would suggest if there is any shared code between the versions for different platform it is easier to have a single repository and then try to organise it for building different versions than try to synchronising changes between multiple repositories.

If you wanted a little more structure, make implementations often have a feature called VPATH which is a search path a bit like the command search path that allows make to search for source files beyond the directory containing the Makefile. This is often used, for example, to build into a different directory than the source and can be used to implement separate optimised and debug builds. I have also used it at work to build the same code for several different CPUs when we had a heterogeneous network of Unix workstations. The very same mechanism could be used to have directories per platform with the platform-specific items in, including any custom Makefile, but referring to the common directory for the shared code. It is even possible to combine the approaches - i.e. build into a separate tree and have platform-specific and common source folders.

Regarding things such as Makefiles or the project files for an IDE, I would include these in the repository to be version controlled like anything else. I have not used Visual Studio much but I note its project file is XML so version controlling that should work fine. Most modern VC systems can handle binary files too, I am sure git can.

What I don't know is how easy it is, or if it is even possible, to set up the platform-specific IDEs to work within a particular directory but refer out to a common directory as needed, i.e. the equivalent for the Makefile VPATH. For that, you'd have to experiment or hope an expert on the indidivual IDEs pops up.

The other thing - don't be afraid of not getting it right first time. You can always move files around in the repository if you find a better way.

[Richard Russell]

Commit in what you have, as it is, and learn about how the system works.

I honestly don't think I could learn "how the system works" at my age and with my deteriorating mental capacity. It's been suggested that I could simply create a zip file and let somebody else do the work of putting it on Github (or whatever) and that is tempting, but I would still need advice on how to structure the project in the zip.

You've said that you want to structure your project but not why.

My objective is simply to put it into the public domain, so that it doesn't vanish when I die (there's also a school of thought that interest in BBC BASIC could be stimulated by the source being available for study). But since it's an active project that regularly receives updates I don't want to archive a snapshot that will be out of date within weeks. It would have to be in a form in which new versions could be generated in a safe and straightforward way (so just one copy of common code, for example), which I assume implies that it must be 'structured'.

The source is therefore all on one directory, there is a Windows-specific Makefile that includes the right set of modules for the Windows version and a GNU autotools generated Makefile that includes the right set of modules for the Linux build.

I know nothing about 'GNU autotools' (and I note that davidb says that makefiles should be written by hand). As far as each platform's build including "the right set of modules" is concerned, how is that actually achieved? I've had a quick look at the SDL build process and that first copies the wanted source files into a platform-specific directory; is that a good method?

I think what I'll do is try to create a zip file, then people can comment on that without worrying about the complication of Github. I should perhaps make clear, again, that I am not proposing to release the assembler code currently used to build BB4W and the 32-bit x86 builds of BBCSDL, but only the C source currently used for the ARM and 64-bit x86 builds.

[Coeus]

I know nothing about 'GNU autotools' (and I note that davidb says that makefiles should be written by hand)...

David said "if they are written by hand". It is generally seen as best practice to put in the repository the files that are the result of your own manual work and leave out those that are machine-generated from other files you did generate by hand. So, in the case of GNU autotools there is a Makefile.am which is generated by hand which gets turned into a Makefile by automake so I add Makefile.am to the repository and not Makefile. Makefile.win is generated by hand so that is in the repository.

I am not suggesting, either, that you dive into GNU autotools. It solves a particular problem in resolving differences for the many Unix-family operating systems and is therefore supposed to save the complexity of doing this yourself but it is, itself, quite complicated and therefore a significant effort to learn.

As far as each platform's build including "the right set of modules" is concerned, how is that actually achieved?

A Makefile has rules to say what goes into each program being built so you only include the modules you need in the rule and the other are ignored. As an example, here is Makefile.win from B-Em:

Code: Select all

VPATH = . resid-fp NS32016 darm

CPP  = i686-w64-mingw32-g++
CC   = i686-w64-mingw32-gcc
WINDRES = windres.exe

# The following flags are used by PiTubeDirect Co Pros:
#                BEM - fixes for compilation in B-Em envorinment
#   INCLUDE_DEBUGGER - include the cpu_debug implementation
# USE_MEMORY_POINTER - do not assume Co Pro memory starts at address 0

COMMON_FLAGS = -O3 -Wall -I ../../allegro5/include -DBEM -DVERSION=\"Win32\" -DINCLUDE_DEBUGGER -DUSE_MEMORY_POINTER
CFLAGS       = -std=gnu99 $(COMMON_FLAGS)
CXXFLAGS     = $(COMMON_FLAGS)

OBJ = \
    6502.o \
    6502debug.o \
    6502tube.o \
    65816.o \
    acia.o \
    adc.o \
    arm.o \
    darm.o \
    darm-tbl.o \
    armv7.o \
    armv7-tbl.o \
    thumb.o \
    thumb-tbl.o \
    thumb2.o \
    thumb2-decoder.o \
    thumb2-tbl.o \
    cmos.o \
    compact_joystick.o \
    compactcmos.o \
    compat_wrappers.o \
    config.o \
    csw.o \
    ddnoise.o \
    debugger.o \
    disc.o \
    fdi2raw.o \
    fdi.o \
    gui-allegro.o \
    i8271.o \
    ide.o \
    joystick.o\
    keyboard.o \
    keydef-allegro.o \
    logging.o \
    main.o \
    mem.o \
    midi-windows.o \
    model.o \
    mouse.o \
    music2000.o \
    music4000.o \
    music5000.o \
    pal.o \
    savestate.o \
    scsi.o \
    sdf.o \
    serial.o \
    sn76489.o \
    sound.o \
    sysacia.o \
    sysvia.o \
    tape.o \
    tapecat-allegro.o \
    tapenoise.o \
    tsearch.o \
    tube.o \
    uef.o \
    uservia.o \
    vdfs.o \
    via.o \
    vidalleg.o \
    video.o \
    wd1770.o \
    win.o \
    x86.o \
    x86dasm.o \
    z80.o \
    z80dis.o \
    resid.o \
    b-em.res

NS32KOBJ = \
    32016.o \
    32016_debug.o \
    Decode.o \
    mem32016.o \
    Trap.o \
    Profile.o \
    NSDis.o

SIDOBJ = \
    convolve.o \
    envelope.o \
    extfilt.o \
    filter.o \
    pot.o \
    sid.o \
    voice.o \
    wave6581__ST.o \
    wave6581_P_T.o \
    wave6581_PS_.o \
    wave6581_PST.o \
    wave8580__ST.o \
    wave8580_P_T.o \
    wave8580_PS_.o \
    wave8580_PST.o \
    wave.o

LIBS = -L ../../allegro5/lib -lz -lallegro_audio -lallegro_acodec -lallegro_primitives -lallegro_dialog -lallegro_image -lallegro_font -lallegro -mwindows -lgdi32 -lwinmm -lstdc++

all : b-em.exe hdfmt.exe

b-em.exe: $(OBJ) $(SIDOBJ) $(NS32KOBJ)
	$(CC) $(OBJ) $(SIDOBJ) $(NS32KOBJ) -o "b-em.exe" $(LIBS)

clean :
	del *.o *.exe *.res

%.o : %.c
	$(CC) $(CFLAGS) -c $<

%.o : %.cc
	$(CPP) $(CXXFLAGS) -c $<

b-em.res: b-em.rc
	$(WINDRES) -i b-em.rc --input-format=rc -o b-em.res -O coff

hdfmt.exe: hdfmt.c
	$(CC) $(CFLAGS) -o hdfmt.exe hdfmt.c

Three variables, OBJ, NS32KOBJ and SIDOBJ are each set to lists of modules and the lines:

Code: Select all

b-em.exe: $(OBJ) $(SIDOBJ) $(NS32KOBJ)
	$(CC) $(OBJ) $(SIDOBJ) $(NS32KOBJ) -o "b-em.exe" $(LIBS)

Tell make to link that set of object files into the b-em.exe excutable and other rules tell make how to generate those object files from their corresponding source files by running the compiler on them. As the file linux.o (compiled from linux.c) containing linux-specific code doesn't appear in any of those variables it doesn't get compiled or linked when building for Windows.

Note also that this Makefile uses VPATH because there are some modules that have been imported into B-Em from elsewhere each of which lives in a sub-directory, but which are linked into B-Em directly, not built into a separate library.

What I cannot advise on is how to use Visual Studio or one of the mobile phone devlopment IDEs to add/remove from the set of files that will be compiled and linked as part of the project, though I hope that is possible.

... I've had a quick look at the SDL build process and that first copies the wanted source files into a platform-specific directory; is that a good method?

There is nothing wrong with that as long as the copying is automated as part of the built process. What I think you want to avoid is having to maintain multiple copies of the same file in different directories. If you work on, and have checked into the repository, a single copy of each source file it doesn't matter if the build process takes temporary copies as part of that process. It may not be as efficient as simply referring to the shared copy (VPATH etc.) but, as long as you are not tempted to edit the temporary copies, it shouldn't result in a muddle.

[Richard Russell]

It may not be as efficient as simply referring to the shared copy (VPATH etc.) but, as long as you are not tempted to edit the temporary copies, it shouldn't result in a muddle.

I've never encountered VPATH; it probably makes copying the source files unnecessary. But I would rather concentrate on building a working executable (which at the moment it isn't) than worry about the style, which could be improved by somebody other than me at a later date.

Does anybody here have experience of building an Android or iOS app from a makefile, rather than using an integrated tool such as Xcode? It would be nice to include those targets in the zip, but at the moment I can't.

[BigEd]

I think what I'll do is try to create a zip file, then people can comment on that without worrying about the complication of Github. I should perhaps make clear, again, that I am not proposing to release the assembler code currently used to build BB4W and the 32-bit x86 builds of BBCSDL, but only the C source currently used for the ARM and 64-bit x86 builds.

I think that should be excellent and sufficient. As for the code being a moving target, it's very much the function of the source control system to accept updated source files and deal with the updates gracefully.

[Richard Russell]

Here you go, for good or ill, a zip file containing the source code of BBCSDL plus makefiles for 32-bit Windows, 64-bit Windows, 64-bit Linux and Raspberry Pi (Raspbian). Hopefully MacOS, Android and iOS will follow, but as they use IDEs I'm not sure how best to incorporate the build information.

The code is about as far removed from 'vanilla' C as it's possible to get (maybe 'saffron' C?) and will only compile using GCC (or Clang for iOS). Large chunks of it have been 'mechanically' translated from assembler code, and it shows. C purists should look away, for fear of having conniptions.

[Richard Russell]

… and before somebody complains about the "warning: the use of `tempnam' is dangerous" linker message, it's not true. There is no inherent danger in calling 'tempnam', the issue arises only if the string returned by that function is used to open a 'temporary file' and that is not the case in BBCSDL. Personally I think it's ridiculous to issue a warning that is actually a lie; since it's possible to call 'tempnam' in a perfectly safe fashion there should at least be a way of disabling the warning (as you can compiler warnings), but AFAIK there isn't.

[Coeus]

Here you go, for good or ill, a zip file containing the source code of BBCSDL plus makefiles for 32-bit Windows, 64-bit Windows, 64-bit Linux and Raspberry Pi (Raspbian)....

Richard, thank you for this. I believe this is good for the community and good for the future of BBC Basic.

Hopefully MacOS, Android and iOS will follow, but as they use IDEs I'm not sure how best to incorporate the build information.

These IDEs must keep this information somewhere. Do they have the equivalent of the Visual Studio "project" file? Visual Studio project files are often checked into a repository and should be enough for someone else to import the project into Visual Studio.

The code is about as far removed from 'vanilla' C as it's possible to get (maybe 'saffron' C?) and will only compile using GCC (or Clang for iOS). Large chunks of it have been 'mechanically' translated from assembler code, and it shows. C purists should look away, for fear of having conniptions.

Perhaps that just marks me as not a purist, but I think you should just feel proud of what can be done with it, as you said yourself in the thread about speed. Other people looking and saying to themselves "I would not have done that like that" is like the tradesman who comes to your house and tut tuts about the work of the previous tradesman. It doesn't mean the previous tradesman was bad, just that the two have picked up different ideas of best practice.

On needing GCC, It is usually the view that once should try to write standard (ANSI/ISO) C rather than rely on a particular compiler but GCC is itself so portable that need not be a big concern.

[Richard Russell]

GCC is itself so portable that need not be a big concern.

Indeed, and it's become such a de-facto standard that Clang copies many of its extensions, built-ins and intrinsics (luckily for me, because otherwise the iOS port would have been much more difficult). One GCC feature I take advantage of, that Clang doesn't support, is 'register variables' (variables which are kept continuously in registers that the programmer specifies). It's interesting that when you read the justification, or not, for register variables (and for Clang not implementing them) it says that almost always the compiler/optimiser will do a better job of allocating variables to registers than you can, with the possible exception of language interpreters! Well, quite.

[dhg2]

Thanks Richard. As Coeus said, this is very good for the community, and I think BBC BASIC has a bright future ahead.

[richardtoohey]

Hopefully MacOS, Android and iOS will follow, but as they use IDEs I'm not sure how best to incorporate the build information.

These IDEs must keep this information somewhere. Do they have the equivalent of the Visual Studio "project" file? Visual Studio project files are often checked into a repository and should be enough for someone else to import the project into Visual Studio.

Again, maybe to just get started, compress & upload the source code for each platform with appropriate how-to-build-in-XXX.txt (where XXX is the IDE that is used for that platform/version) and "we" (cough) can work out from there what the IDE does - project files, make files, whatever.

At least if someone else can build the binaries following the instructions you provide - nothing is lost and there's real working code that can be examined, cunning plans plotted, etc. If you have an accident "Bus? What bu...." then at least the code is safe, your work is not lost & the world knows how to build it.

It's not perfect, it's not your end goal - but a step towards both.

And as others have said: Thank you.

[Richard Russell]

Again, maybe to just get started, compress & upload the source code for each platform

The 'source code' is already in the zip I have made available; apart from two files it's shared between all the editions (and in the case of those two files the Android and iOS versions are included).

with appropriate how-to-build-in-XXX.txt

That makes it sound easy, but it isn't. To put it into perspective, even I have forgotten what I did to get the iOS edition to build: if the Mac were to crash I wouldn't quickly be able to reconstruct the build environment myself, let alone somebody else (as I think most people know, one of the main reasons for releasing the source now is my rapidly deteriorating memory)!

[richardtoohey]

Ah, I see.

For iOS: have you got any notes/recollections of how you did this? Sounds like the answer is no.

Presumably XCode on a Mac (not that I'm an expert, but I think that's what you need?) I've got a Mac set-up so I can give things a go, but there are (hopefully) people on the forums that know more than me.

But if you've got any recollections on steps you took, that would help. If not, there's always Google, so we'll give it a go.

[scruss]

Richard - one really nice thing about having the source code here in front of me is that it includes a runnable x86_64 version. The previous releases required 32-bit compatibility libraries to run on 64-bit Ubuntu, and these just never worked correctly for me.

At least on the Linux side, your code organization looks pretty tidy. I've seen open source projects with much more vexing build setups (including one that required their own build tool that half-replicated the abilities of make, except it was written in PHP, with all customization directions written in Spanish) so this one won't be difficult to archive.

[Richard Russell]

One really nice thing about having the source code here in front of me is that it includes a runnable x86_64 version.

The 64-bit Linux edition has been downloadable from my website for a month or so, although only linked from the list of changes; it was mentioned in the release announcement. The reason it's not an 'official' release is the obvious one: unless and until there's an x86_64 assembler, it doesn't qualify as 'proper' BBC BASIC! In the source zip there are three dummy files: bbasmb_x86_32.TODO.c, bbasmb_x86_64.TODO.c and bbasmb_arm_64.TODO.c; these await somebody (and sadly it is unlikely to be me) creating them! The one working assembler (bbasmb_arm_32.c) can be used as a template, although the others will need to be far more complicated.

[simonm]

If you think it appropriate Richard, your project could be easily added as-is to the stardot GitHub organisation alongside other open source community projects. Github is actually quite straight forward to use once you acquire a few bits of know how, and I'm continually impressed with how collaborative it is and how often other folks are willing to pitch in and help with development and enhancements etc.

[Richard Russell]

your project could be easily added as-is to the stardot GitHub organisation

What are the pros and cons of doing that rather than using my own GitHub account, for example? I always think of StarDot as being closely associated with Acorn, and 'my' BASICs (unlike Brandy for example) are absolutely not!

[Richard Russell]

I've got a Mac set-up so I can give things a go, but there are (hopefully) people on the forums that know more than me.

Currently there's only a 32-bit MacOS edition (using the x86 assembler version of my BBC BASIC interpreter); it's built using Xcode but an ancient 32-bit version running on an equally ancient Mac OS Snow Leopard. So whilst it incorporates an assembler and has good compatibility with BB4W, it's not really relevant in the context of this thread (and in any case Apple have announced that MacOS will be dropping support for 32-bit apps soon).

Therefore my assumption is that any MacOS edition created from the sources I have released would be 64-bit and built on a 'modern' Mac using the current Xcode, and would need to be largely created from scratch. Like the 64-bit Linux edition it needs an x86_64 assembler to be 'complete'. Accordingly I can't really contribute anything useful at the moment.

[scruss]

The 64-bit Linux edition has been downloadable from my website for a month or so

Yes, I just noticed that. It installs and runs beautifully. Thank you!

The reason it's not an 'official' release is the obvious one: unless and until there's an x86_64 assembler, it doesn't qualify as 'proper' BBC BASIC!

While an assembler might be part of the 198x BBC BASIC specification, I think it has outlived its usefulness. Part of the problem is the multiple processor/platform support: assembly language kills portability. Even on ARM, there's the issue of old-style vs modern instruction format, and there's always someone who wants one or the other. On most 64-bit chips, handwritten assembly language can be much slower than compiler-generated code. For my niche needs (usually numerics with fast floating-point) if I need more speed, I'll rewrite it in Fortran rather than attempt inline assembly language.

[simonm]

What are the pros and cons of doing that rather than using my own GitHub account, for example? I always think of StarDot as being closely associated with Acorn, and 'my' BASICs (unlike Brandy for example) are absolutely not!

An excellent question. There are no right or wrong ways to go about such things imho, and hosting your own projects in your own Github account is also entirely appropriate. I only suggested Stardot as a possible home mainly since you expressed 1) a desire to preserve & open source the code and also 2) that you weren't too sure if you wanted to get involved with Github (or something similar).

A community Github organisation account like Stardot's enables projects to have multiple owners/members rather than being owned by one person, so there's less likelihood of projects being lost if folks delete their Github account, or folks simply want to delegate ownership of a project to the community.

Stardot covers a broad church of valuable projects to be fair - indeed here we are talking about your project within it (and its BBC Basic roots), so it feels like a perfectly reasonable home for it should that be of interest/helpful.

I'm think I'll to write up a separate tutorial on this forum for github, since this type of chat has come up a few times, and perhaps it'll help demystify it a bit for folks who havent used it before.

[Richard Russell]

While an assembler might be part of the 198x BBC BASIC specification, I think it has outlived its usefulness.

I can't agree. It may be that you didn't realise this, but the debugging features (List Variables, Single Step, Profiler etc.) which are part of the BBCSDL IDE currently rely on it, and don't work in the 64-bit editions. So do some of the libraries (e.g. TIMERLIB) which again aren't available in the 64-bit editions.

assembly language kills portability.

Not entirely. For the foreseeable future you would only need to include a maximum of four versions of the code (x86_32, x86_64, ARM32, ARM64) to cover all the bases, and probably just the two 64-bit versions would be sufficient. Given that the typical use of assembler code in BBC BASIC programs is for short routines, writing both x86 and ARM versions shouldn't be onerous.

On most 64-bit chips, handwritten assembly language can be much slower than compiler-generated code.

That may have been true of some architectures (Itanium, Alpha, PowerPC etc.) in which it was indeed difficult to write high performance hand-assembled code, in fact code that would run at all. But x86_64 CPUs are still 'assembler friendly' in that they support out-of-order execution, register renaming etc. in the silicon, so the kinds of optimisations a compiler can achieve, whilst undoubtedly helpful, aren't that great. The 32-bit C version of my interpreter runs at roughly half the speed of the assembler version, and I have no particular reason to expect that to be very different at 64-bits.

[Richard Russell]

I'm think I'll to write up a separate tutorial on this forum for github, since this type of chat has come up a few times, and perhaps it'll help demystify it a bit for folks who havent used it before.

That would certainly be very helpful to me.