KerboScript Machine Code

Compiling to a KSM File

When you run your Kerboscript programs, behind the scenes they get compiled into a form in memory that runs much smoother but at the same time is quite hard for a Kerbal to read and understand. The actual computer hardware built by your friends at Compotronix incorporated actually run the program using these tiny instructions called “opcodes”. In the early days of room-sized computers before we were able to get them down to the compact size of just a meter or so across, all programmers had to use this difficult system, referred to as “machine language”. Ah, those were heady days, but they were hard.

The commands you actually write when you say something like SET X TO 1.0. are really a euphemism for these “machine language” opcodes under the surface.

When you try to “RUN” your script, the first thing that kOS does is transform your script into this ancient and arcane “machine language” form, storing it in its memory, and from then on it runs using that.

This process of transforming your script into Machine Language, or “ML” is called “Compiling”.

The “RUN” command does this silently, without telling you. This is why you may have noticed the universe slightly stutter for a moment when you first run your program. Compiling is hard work for the universe to do.

Why Do I Care?

Warning

This is an experimental feature.

The reason it matters is this: Although once it’s loaded into memory and running, these opcodes actually have a lot of baggage and take up a lot of space, when they’re stored passively on the disk not doing anything, they can be smaller than your script programs are. For one thing, they don’t care about your comments (only other Kerbals reading your script do), and they don’t care about your indenting (only other Kerbals reading your script do).

So, given that the compiled “ML” codes are the only thing your program really needs to be run, why not just store THAT instead of storing the entire script, and then you can put the ML files on your remote probes instead of putting the larger script files on them.

And THAT is the purpose of the COMPILE command.

It does some, but not all, of the compiling work that the RUN command does, and then stores the results in a file that you can run instead of running the original script.

The output of the COMPILE command is a file in what we call KSM format.

KSM stands for “KerboScript Machine code”, and it has nearly the same information the program will have when it’s loaded and running, minus a few extra steps about relocating it in memory.

How to Use KSM Files

Let’s say that you have 3 programs your probe needs, called:

  • myprog1.ks
  • myprog2.ks
  • myprog3.ks

And that myprog1 calls myprog2 and myprog3, and you normall would call the progam this way:

SWITCH TO 1.
COPY myprog1 from ARCHIVE.
COPY myprog2 from ARCHIVE.
COPY myprog3 from ARCHIVE.
RUN myprog1(1,2,"hello").

Then you can put just the compiled KSM versions of them on your vessel and run it this way:

SWITCH TO ARCHIVE.

COMPILE myprog1.ks to myprog1.ksm.
COPY myprog1.ksm to 1.

COMPILE myprog2. // If you leave the arguments off, it assumes you are going from .ks to .ksm
COPY myprog2.ksm to 1.

COMPILE myprog3. // If you leave the arguments off, it assumes you are going from .ks to .ksm
COPY myprog2.ksm to 1.

SWITCH TO 1.
RUN myprog1(1,2,"hello").

Default File Naming Conventions

When you have both a .ks and a .ksm file, the RUN command allows you to specify which one you meant explicitly, like so:

RUN myprog1.ks.
RUM myprog1.ksm.

But if you just leave the file extension off, and do this:

RUN myprog1.

Then the RUN command will first try to run a file called “myprog1.ksm” and if it cannot find such a file, then it will try to run one called “myprog1.ks”.

In this way, if you decide to take the plunge and attempt the use of KSM files, you shouldn’t have to change the way any of your scripts call each other, provided you just used versions of the filenames without mentioning the file extensions.

Downsides to Using KSM Files

  1. Be aware that if you use this feature, you do lose the ability to have the line of code printed out for you when the kOS computer finds an error in your program. It will still tell you what line number the error happened on, but it cannot show you the line of code. Just the number.
  2. Know that you cannot view the program inside the in-game editor anymore when you do this. A KSM file will not appear right in the editor. It requires a magic tool called a “hex editor” to properly see what’s happening inside the file.
  3. The file isn’t always smaller. There’s a threshold at which the KSM file is actually bigger than the source KS file. For large KS files, the KSM file will be smaller, but for short KS files, the KSM file will be bigger, because there’s a small amount of overhead they have to store that is only efficient if the data was large enough.

More Reading and Fiddling with Your Bits

So, if you are intrigued by all this and want to see how it all REALLY works under the hood, Computronix has deciced to make internal document MLfile-zx1/a on the basic plan of the ML file system open for public viewing, if you are one of those rare Kerbals that enjoys fiddling with your bits. No, not THOSE kind of bits, the computery kind!