rb+ tutorial #1: Setting up and configuring rb+ from scratch

[ggn]

I've been meaning to make such a post for quite a while now but I always either put it off or thought it'd be too much work. Whatever the reasons, it simply never got done. So I thought I'd try to make an effort towards it and enrich it if people still have questions or some steps are missing/confusing.

 

Don't forget to click on the pictures to show them full size.

 

Windows guide

 

Step 1: obtaining rb+

 

Even from the start there are multiple choices: you can either download the latest version from github or bitbucket, or download the latest installer. The difference between the installer version and latest is that the installer is generally lagging in features but is more stable and as bug free as possible. I'll cover the latest version for now and the installer at a later point.

 

If you're proficient with git you can always clone the repository instead of downloading it, so keeping up to date will simply require a pull/merge action (also it's much faster to do pull/merges than downloading the archive from scratch every time just to update a few files, as is usually the case when updates are pushed). Otherwise, go to your favorite site: github or bitbucket. For github just press the "clone or download" button and "download zip" at the pop up. Save the zip file.

 

Once the download is done, you can unzip the file pretty much wherever you like (and have permission to). You'll then have a lot of files inside a folder called "bcx-basic-jaguar". You can rename that folder too of course.

 

Step 2: first steps

 

You're now ready to start using the Basic! Open a Windows command prompt, cd to the location you unzipped the folder (for example type "cd c:\rb+" if you unzipped to c:\ and renamed the folder to rb+) and build a sample project by typing "build nyandodge". The project should build and virtualjaguar should appear on screen with the game running:

 

[EDIT] If you're running 32bit Windows, you'll need to replace virtualjaguar.exe (inside the "bin" folder) with a 32bit version, latest releases are here. Thanks to neo for the heads up!

 

(for what it's worth, I'm not using Windows command prompt, but instead I've switched to using cmder which is a reskinned ConEmu with some added stuff - so many choices again! Again, it's not mandatory to use conemu/cmder, simple cmd.exe will do the trick.)

 

If you want to create a new project just go to the console again and type "build <myproject> new", replacing <myproject> with the name of your project (no spaces in the name please!). Building the project should give you something like this:

 

 

 

 

 

 

 

 

Now you can navigate to the "projects" folder, open the folder that matches the name of your project, open <myproject>.bas and start editing the file! Keep the console open so you can rebuild the project every time you wish so.

 

Step 3: streamlining

 

If you stopped reading the guide on step 2 and started trying things out you'll soon realise that it switching between editor and console to edit and build can become tedious. So let's make this less painful! (note that all these steps are not mandatory, you can configure your own environment as it suits you if you think this is clunky).

 

First of all, go and download Notepad++. It's free, open source (not that we care much!) and it's got a lot of neat features built in. After installing and running it, it's time to customise it. Open the plugin manager from the menu:

 

Go to the "installed" tab and check if "NppExec" plugin is installed. If not, go to "Available" tab, find the plugin and install it.

[EDIT] There are high chances you won't be able to see an available plugins list, and NppExec won't be available to you. If this happens then read neo's post and download the plugins manually.

 

Let's add some syntax highlighting. Enable "Visual Basic" from the Language menu. It's not 100% matching the syntax of rb+ but it's good enough!

 

[EDIT] Alternatively you can use OMF's syntax highlighting efforts. To install (thanks to Gemintronic for the test and guide):

• In Notepad++ go to "Define your language..." and use the [ Import ] button on the .xml file omf made
• In the "User Defined Language" window select Reboot Basic Plus and SAVE AS the language. I called it "rB+"
• Now in the languages menu drop down list you'll see "rB+". Select that like it's hot.

Now, let's add the magic bits! Bring up the "execute" dialog from plugins->nppexec->execute menu or hit f6. Add the following 3 lines to the command prompt:

npp_save
CD $(CURRENT_DIRECTORY)\..\..
build.bat $(NAME_PART)

This will save the current opened file, go to the rb+ top directory and build the code. A small window will also pop up at the bottom of the notepad++ window, informing you of the build process. So you can catch any errors or warnings there. After the first time you do this you should be able to hit ctrl-f6 to build instantly without having to open the dialog box again! Success!

 

Finally, if you want to change the shortcut keys, go to the shortcut mapper dialog:

 

Then click on "plugin commands" tab, scroll down till you find "execute" and "direct execute previous", click those, then "modify", then choose your favorite key or key combo (personally I use F7 for direct execute previous and never bother with execute).

 

Done!

 

Addendum 1: vim setup

 

Well, you can't just hate something that originates from the Atari ST, can you? (if you don't believe me, just check out wikipedia)

 

Love it or hate it vim is one of the most used editors on the planet, but there's so many extensions and "cool" stuff you can do with it that it bewilders a lot of people. Still, if you can stick to learning 10-15 shortcuts and tricks that's all you're going to need in your lifetime. So let me show you how you can build rb+ stuff with it like we do with Notepad++.

 

First of all, vim auto detects the file syntax from the extension, so we were lucky to use the .bas extension! It uses some flavour of basic which is "good enough" for our purposes. However if anyone wants to try customising the syntax highlight - good luck and please share the results with the rest of us! Here's how it looks on my machine:

 

 

Now vim being an old dinosaur does actually have support for compilation from the editor and opening a window with any errors and jumping into them. We just have to ask it politely!

 

So open your vimrc file (this can be in various locations, on linux it should be ~/.vimrc, on Windows it's usually on c:\users\<username>\_vimrc) and add the following:

 

""""""""""""""""""""""""""""""""
" Lifted from https://hero.handmade.network/forums/code-discussion/t/709/p/4135 and hacked around a bit by ggn
" Ensure the buffer for building code opens in a new view
set switchbuf=useopen,split
comp gcc

" Build helper function
function! DoBuildBatchFile()
    " build.bat
    set makeprg=build
    " Make sure the output doesnt interfere with anything
    " (ggn): the ! is needed so copen won't open a window with the first
    " warning/error 
    silent make!
    " Open the output buffer
    "copen
    cwindow
    echo 'Build Complete'
endfunction
"Go to next error
nnoremap <F6> :cn<CR>
"Go to previous error
nnoremap <F5> :cp<CR>
" Set F7 to build.
nnoremap <F7> :call DoBuildBatchFile()<CR>
""""""""""""""""""""""""""""""""

So what does that do? Firstly it defines some mumbo jumbo vimscript function to tell it to execute a file called build.bat - this should be on the same directory vim was run from, so typically the directory your .bas file exists. Then it maps key F7 to do run build.bat and if any errors occur, open a window to show them. (that window can be opened using :copen regardless). In the case of errors, F5 and F6 will jump to the previous and next site of error. Beware though, this will jump at the translated .c file, not our .bas file! So there might be some initial confusion about this at first but it is usuable with a bit of practice .

 

Before trying this out though you also need to create a build.bat file. Here's what I use:

 

cd ..\..\
call build myproject

And that's it. Of course you can extend this to have multiple build.bat files and map different keys to run them - for example you might want a clean build, or build+send to skunkboard, or just build (BOSSMODE).

 

Addendum 2: 4coder setup

 

4coder is an up-and coming editor developed by a single person (Allen Webster). While it's focused on C/C++ so far it has been my main editor for a few months now. I quite like the smooth scrolling, quite sensible defaults, and keybindings, although learning to select/copy/paste can be bewildering at first! Also it's commercial with a demo version free to try which is currently what I use. It still has a few nuiances which I've pointed out to the author and it's nice to see they'll get addressed so I'll quite possibly buy this soon.

 

Anyway, it turns out it's quite easy to use with rb+. There's no syntax highlight for it yet (although it really doesn't bother me) but you can automate your builds easily. It turns out that the editor actually has a built-in shortcut to call a "build.bat" as the author is a fan of this method! So simply use the sample build.bat I mentioned above in the vim section and hit alt-m. That's it!

 

Done!

 

That's the end of the guide for now. If things are missing or are still not clear, leave a comment below and I'll address and update this post when possible.

Edited April 8, 2018 by ggn

[ggn]

Linux guide

 

Step 1: Setting up

• Install wine and git. For the record I'm using wine 1.6. On debian based systems it's

  sudo apt-get install wine git

• Optionally, compile and install virtualjaguar on your system.
• Go to the folder you want rb+ to reside (for example "cd ~").
• Type

  git clone https://bitbucket.org/ggnkua/bcx-basic-jaguar.git

  git will create a folder called "bcx-basic-jaguar" and download the files there.

Step 2: Try it out

 

Let's see if it's working. type "cd bcx-basic-jaguar" and then "wineconsole build.bat nyandodge". First time wine runs there is a long pause on my machine here (invoking Cthulu is never an easy process) so be prepared for it. The project should fully build and even open the Windows version of virtualjaguar running the compiled binary! If this doesn't happen in your machine you can easily compile and run a native version of virtualjaguar.

 

Step 3: Pimp my linux

 

I know that linux is all about freedom of expression etc so I should just let people roll their own thang and all. All the same I'll leave an extra step here on how to automatically build using at least one editor, Geany.

• First, install the editor

  sudo apt-get install geany

• Run it from the menu or the console.
• Open a .bas file you want to edit (say projects/nyandodge/nyandodge.bas. Geany has freebasic syntax highlighting and it seems to map mostly fine with rb+
• Go to menu Build->Set Build commands.
• In the "FreeBasic commands" click on the empty button underneath "Compile" and edit the text to say "rb+ build". In the command option type

  wineconsole build.bat "%f"

  

   

  In "working directory" type the absolute path you placed rb+ - for me it's "/hone/ggn/bcx-basic-jaugar". Press ok.

• Go to menu "Build->rb+ build" or hit f9 on your keyboard (at least it's auto mapped to f9 here). Things will build and run as like they did on the console!

More hardcore linux users will probably want to use their favorite editor like vim or emacs or whatever, so I'm sure they already know how to run build commands. Good luck to them! I can only hint that they will need to change working directory to rb+ root and run "wineconsole build.bat <projectname>". Edited April 14, 2017 by ggn

[omf]

While your at it setting up Norepad++ to be your RB+ editor you may as well add some additional support by adding syntax hi lighting, i have been working on this for a long time now and as new stuff gets added i have been adding it to the variables list, so it is ongoing.

 

i know that there was a problem with this if you didn't use a white background to notepad++ but i think i have now fixed this.

 

import the custom language into notepad++ and select it from the language menu to allow rb+ syntax hi lighting

 

 

if anyone spots issues, please report them to me so i can fix the file for future

 

 

rb+ syntax highlight.rar

[+Gemintronic]

Still trying to figure this out myself. I think Windows users might need to change "rb+ syntax highlight" to "rb+ syntax highlight.xml" for the import dialogue to see it in notepad++

[omf]

oh didnt it do that when i exported, damnit!!!

yes you will need to do that

[neo_rg]

Thanks for starting this thread ggn. I think it was about time I pulled my finger

out and installed rB+, seeing as I keep encouraging other people to try it out.

 

I did run into a couple of problems that were either my bad luck, laptop running

XP or maybe the wind was blowing in the wrong direction on the day in question.

Hoping that sharing my problem and the solution will help out others.

 

Installed rB+ like instructed with no problems at all. Saved into the C drive in a

folder called rb+. had a quick sneaky go at building one of the projects using

windows command prompt. It all worked but died on the bit where it lauched

VJ saying it wasn't a WIN32 application.

 

Solution to that problem was to overwrite the version of VJ in the rb+/bin/ folder

with the lastest version, result being that I can now build projects and have them

run in VJ.

 

Installed Notepad++ as instructed but had a couple of problems getting the plugins

manager to download a list of available plugins. Had to manually download a plugin

manager zip file and extract some files from their respective folders into the following folders..

 

C:\Program Files\Notepad++\plugins folder

C:\Program Files\Notepad++\updater folder

 

Plugin manager now working but I was unable to download the nppexec file from the

list. I tried a few times changing various things in the setting of the plugin manager

but nothing worked.. bad internet or a server down who knows.

 

I fixed the NppExec problem manually by downloading the 053_dll zip file and extracting

the NppExec.dll to the following folder

 

C:\Program Files\Notepad++\plugins

 

I then rebooted the program and followed the rest of instructions for making a compile

shortcut which works as it should. Hope this helps someone if you run into the same

problems I did.

 

NppExec_053_dll_Unicode.zip

PluginManager_v1.4.4_UNI.zip

[+Gemintronic]

Today I got syntax highlighting to work using omfs .xml file and neo_rgs updated files. Basically:

 

* Install Notepad++ (32-bit)

* Copy neo_rgs files to the same directories in Notepad++

* In Notepad++ go to "Define your language..." and use the [ Import ] button on the .xml file omf made

* In the "User Defined Language" window select Reboot Basic Plus and SAVE AS the language. I called it "rB+"

* Now in the languages menu drop down list you'll see "rB+". Select that like it's hot.

 

Not patting myself on the back. Just reiterating the process that worked for me

[ggn]

Thanks to everyone for the feedback and suggestions so far! I've mostly edited my initial post with your comments, and also added a more detailed linux guide.

[Positron5]

Hi everyone.
Ive just installed rb+, that's one more crazy jag coder.
I hope to learn more about the rules and techniques for jag development. Thank you

[Fredifredo]

After a lot of problems ( 2 computer crashs + housebreaking ), I want to restart all from the beginning ...with an other stupid project ( using some Alamo ideas )

thanks for the tutorial !

[Christos]

BTW,

 

I've been experimenting with VIsual Studio Code, which does a good job at highlighting RB+ as well.

 

But you will need a build system.... this should do the job:

 

1, Open the folder your project lies in.

2. Set cmd as your internal terminal

{"terminal.integrated.shell.windows": "C:\\Windows\\System32\\cmd.exe"

}

2. Use this task.json

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build Jaguar",
            "type": "shell",
         
            "windows": {
                "command": "cd ..\\..  && build.bat ${fileBasenameNoExtension}"
                
            
            }, 
            "group": {
                "kind": "build",
                "isDefault": true
            },  
            "presentation": { 
                "reveal": "always",
                "panel": "new"
            }
        }
    ]
}

4. ......

 

5. Profit

 

 

[EDIT] moved to this thread from "tools of the trade" as it's more fitting here!

Edited February 7, 2018 by ggn

[ggn]

Thanks for starting this thread ggn. I think it was about time I pulled my finger

out and installed rB+, seeing as I keep encouraging other people to try it out.

 

I did run into a couple of problems that were either my bad luck, laptop running

XP or maybe the wind was blowing in the wrong direction on the day in question.

Hoping that sharing my problem and the solution will help out others.

 

Installed rB+ like instructed with no problems at all. Saved into the C drive in a

folder called rb+. had a quick sneaky go at building one of the projects using

windows command prompt. It all worked but died on the bit where it lauched

VJ saying it wasn't a WIN32 application.

 

Solution to that problem was to overwrite the version of VJ in the rb+/bin/ folder

with the lastest version, result being that I can now build projects and have them

run in VJ.

 

Installed Notepad++ as instructed but had a couple of problems getting the plugins

manager to download a list of available plugins. Had to manually download a plugin

manager zip file and extract some files from their respective folders into the following folders..

 

C:\Program Files\Notepad++\plugins folder

C:\Program Files\Notepad++\updater folder

 

Plugin manager now working but I was unable to download the nppexec file from the

list. I tried a few times changing various things in the setting of the plugin manager

but nothing worked.. bad internet or a server down who knows.

 

I fixed the NppExec problem manually by downloading the 053_dll zip file and extracting

the NppExec.dll to the following folder

 

C:\Program Files\Notepad++\plugins

 

I then rebooted the program and followed the rest of instructions for making a compile

shortcut which works as it should. Hope this helps someone if you run into the same

problems I did.

As an addendum to this: if anyone is using a 64-bit version of notepad++ the attached dll files will not work. However these seem to work fine: https://sourceforge.net/projects/npp-plugins/files/NppExec/NppExec%20Plugin%20v0.5.9.9%20dev/

[sh3-rg]

Just a little note for Windows 10 users who user Windows Defender: it seems it has a habit of deleting the rather important (lol) Buildlink.exe file. Can't really do much without that, cheers Microsoft! Open Windows Defender Security Centre (cool name), Virus & threat protection, Virus & threat protection settings, scroll down to Exclusions - add or remove exclusions, Add an exclusion of type Folder, select your whole rb+ folder or just the rb+/bin folder, and you should no longer have a missing Buildlink.exe.

[+xucaen]

Hi, I am following the guide for Windows. I got it working perfectly on my laptop last night, and now this morning I am trying to do the same on my desktop PC. Both are Windows 10 x64. On the desktop PC I unzipped into a directory rb+ as I did on the laptop, and ran "build nyandodge". On the laptop this works flawlessly, but on the desktop PC I get errors. Not sure what happened, so I figured I'd post here in case this is one of those things that are obvious to everyone but me. I'll keep trying to get it working.

 

edit: I also get a small popup dialog that says "access violation".

 

 

edit 2: I narrowed down the access violation to this line:

buildlink C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\assets.txt C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge

Question: what libs does this tool depend on?

 

 

below is the output of build.bat

C:\Users\James\usr\Atari\Jaguar_Programming\rb+>build nyandodge
  ___           _             ___          _      _
 | _ \__ _ _ __| |_ ___ _ _  | _ ) __ _ __(_)__ _| |_
 |   / _` | '_ \  _/ _ \ '_| | _ \/ _` (_-< / _|_   _|
 |_|_\__,_| .__/\__\___/_|   |___/\__,_/__/_\__| |_|
          |_|
------------------------------------------------------------
Building RAPTOR Basic+ Application

Build error!
Build started on Fri 02/09/2018  9:57:35.82

Adjusting base address for CPU depack routine
Buildlink starting

Checking if assets.txt is newer than any of the build folder files....
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\assets.txt...
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\linkfile.bin...
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\romassets.inc...
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\romassets.h...
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\ramassets.inc...
    Opening - C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\build.log...
    Reading assets.txt line

Assembling raptor skeleton...

Translating .bas file to C...
      BCX Path set to C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\bin\
BCX-32: BASIC to C/C++ Translator by Kevin Diggins (c) 1999-2009
BCX-32 Version 6.00 (2009/06/02)
[Lines In: 138] [Lines Out: 350] [Statements: 111] [Time: 0.05 sec's]
BCX translated C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\nyandodge.bas to C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c For a C Compiler

Compiling C code...
C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c: In function 'void basicmain()':
C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c:119:28: error: 'BMP_ENEMY_clut' was not declared in this scope
C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c:121:14: error: 'Module1' was not declared in this scope
C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c:183:22: error: 'Module2' was not declared in this scope
C:\Users\James\usr\Atari\JAGUAR~1\RB_~1\PROJECTS\nyandodge\build\nyandodge.c:260:24: error: 'BMP_PLAYER_clut' was not declared in this scope
Build error!

C:\Users\James\usr\Atari\Jaguar_Programming\rb+>

[ggn]

Hmm, that's so weird - at least this never happened in all my win10 machines. The only thing that comes to mind is some antivirus doing funky stuff in the background. If you have an antivirus could you try turning it off? Or follow sh3's suggestion above to add an exception to windows defender scanner?

[+xucaen]

Hmm, that's so weird - at least this never happened in all my win10 machines. The only thing that comes to mind is some antivirus doing funky stuff in the background. If you have an antivirus could you try turning it off? Or follow sh3's suggestion above to add an exception to windows defender scanner?

 

Yeah, I think it's something wrong with this PC.. like I said it works flawlessly on my windows 10 laptop. But on this PC, I went and set it up to always run in admin mode and it still asks me to run in admin mode, then fails with access violation. I do a lot of development on this PC and I'm always installing and installing some lib or dev kit or editor so it might be something I have installed or removed that is causing the issue .. Can you let me know which runtime libs Buildlink.exe depends on? Then I'll go and make sure those are installed.

[ggn]

Just the gfa32 runtime - GfaWin23.Ocx which is in the "bin" folder. Perhaps some of its dependencies are not met? Although it would surprise me.

[+xucaen]

Just the gfa32 runtime - GfaWin23.Ocx which is in the "bin" folder. Perhaps some of its dependencies are not met? Although it would surprise me.

It turns out this issue was related to several other issues I was having on this pc. The short of it is Windows 10 is no longer compatible with my CPU and motherboard.

 

I wiped the drive and reinstalled Windows 7. It's working fine now.

[ggn]

Just updated the guide with suggestions for setting up vim and 4coder - can never have too many alternative editor options!

[TXG/MNX]

Just tried invaders project and it works

 

 

[ggn]

Off topic posts moved here, please stop re-posting them here.

[Fredifredo]

Work fine on my Windows 10 X64

 

Using this :

As an addendum to this: if anyone is using a 64-bit version of notepad++ the attached dll files will not work. However these seem to work fine: https://sourceforge.net/projects/npp-plugins/files/NppExec/NppExec%20Plugin%20v0.5.9.9%20dev/

[ggn]

Work fine on my Windows 10 X64

 

Using this :

Return of the fart!

[+Gemintronic]

I just tried the instructions today on a fully updated WIn 10 Pro x64. This includes rB+, CMDer and Notepad++ (x86) install. Adding the rB+ syntax highlighter and NppExec with build script (directly from Notepad++).

 

"success" was measured by creating a new project under CMDer and modifying the main .bas file. Selecting the rB+ syntax highlighting. Running the build script from Notepad++ and watching the compiled ROM play via virtual jaguar.

 

The assumptions of things to do during the process were:

 

* Run Notepad++ installer as admin

* Add the C:\rB+ and C:\bin (location of CMDer) path to the environment

* Uncheck read only on C:\rB+ folder

* Grant Everyone full rights to C:\rB+ folder

* Run CMDer as admin

 

I don't need a cookie. Just adding another data point to the tutorials track record.