Don't forget to click on the pictures to show them full size.
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.
github.png 38.2KB 4 downloads
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:
cli.png 73.91KB 3 downloads
[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:
cli-newproj.png 107.63KB 3 downloads
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:
npppluginmanager.png 13.59KB 10 downloads
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.
nppplugins.png 19.74KB 6 downloadsLet'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.
nppsynatxhighlight.png 43.68KB 6 downloads
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)
nppexec.png 5.66KB 5 downloads
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:
nppshortcut.png 9.51KB 4 downloads
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).
nppshortcutset.png 24.2KB 2 downloads
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:
vim.png 13.62KB 1 downloads
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 myprojectAnd 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!
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 by ggn, Sun Apr 8, 2018 3:50 AM.