Repository Setup for Windows 7 x32

[tajmone]

@Rich15, I'm replying here to your request from #33 (later on we can recycle these instructions and move them to the Wiki):

I would really appreciate some help with the setup. Could I do it even with no knowledge of Ruby?

I use Windows 7 (32-bit) BTW.

I also work on Window, but Win 10 Home, so I'll provide some setup instructions below, hoping that they also work with Win 7.

32-bit Limitation

The main obstacle seems MSYS2, which is 64-bit only, and it's required to install Ruby.

You've already installed Git, so the main obstacle now is Ruby. I'm not sure you'll be able to install it under a 32-bit OS, in that case all I can think of is to provide you with some scripts to build and run the various tests and examples (scripts which we have just deleted to replace them with Ruby Rake instead).

So, let's start and see if there's a workaround to installing Ruby and, if not, we'll come up with a script based solution.

Core Setup Overview

Here's the basic setup that you'll need to use the repository under Windows:

app	version	Chocolatey	Win 7	32-bit
Git for Windows	latest	Git Chocolatey package	✓	✓
MSYS2	latest	MSYS2 Chocolatey package	✓	✗
RubyInstaller	>=3.x.x	Ruby Chocolatey package	???	✓

On top of these, you'll need the ALAN SDK binaries on your SYS PATH (no installation) and some Ruby gems... But first you need to have the above up and running.

I strongly advise to install the above apps using Chocolatey (i.e. if there's a Chocolatey package mentioned in the "Chocolatey" column).

Chocolatey

Chocolatey is a package manager for Windows, which allows you to quickly install and update applications under Windows. To install Chocolatey follow the instructions here:

• https://chocolatey.org/install

Installing Chocolatey takes some patience and fiddling with PowerShell, but once you've done it it's worth the effort since it makes installing any other tools much easier, and will also check dependencies requirements and versions for you, which will avoid breaking applications with premature updates of dependencies (e.g. two apps have a common dependency, but different versions, Chocolatey will only update the latter for a version compatible with both apps).

Win 7 x32 might require you manually install some required dependencies too (see instructions).

Chocolatey GUI

Once Chocolatey is setup an running, you can also Install Chocolatey GUI, which provides a graphic interface for installing and updating applications, instead of using the command line:

• https://community.chocolatey.org/packages/ChocolateyGUI

MSYS2

MSYS2 is now required by Ruby for Windows.
The best way is to install the MSYS2 Chocolatey package via Chocolatey GUI.

Ruby 3

The best way to install Ruby is via the Chocolatey package:

• https://community.chocolatey.org/packages/ruby

The problem is that IRC you can no longer install Ruby without MSYS2, because the latter is used to update/compile Ruby gems and dependencies.

[tajmone]

Ruby 32-bit

@Rich15, I'm a bit confused by the fact that Ruby 3 installer for Windows is indeed available in 32-bit version, although MSYS2 is not.

The Chocolatey package for Ruby doesn't require MSYS2 either.

My best guess is that Ruby 3 will work even on Win 7 32-bit, but possibly with some limitations due to the inability of compiling packages locally (which requires MSYS2).

My advice is to just try and install it, as described above.

Although you don't have to install Chocolatey, I strongly recommend you to install both Chocolatey and Chocolatey GUI, because they will make updating apps much easier (I use for all applications that don' come with an auto-updating feature). Also, Chocolatey will ensure you don't update dependencies in way which might break some applications.

[tajmone]

I have already installed Chocolatey and Ruby.

That's great! Then the remaining steps are quite easy.

Ruby

Now that you have Ruby installed, here a few more tools you might want to look into...

Rake

Ruby already ships with Rake, but on Windows that's a binary pre-compiled, instead of a Ruby Gem. So, if you always want to have the latest version of Rake, you can install it as a gem (it will warn you that you're about to override the predefined binary, but that's fine! Also, if you uninstall the Rake gem, you go back to the default binary):

gem install rake

Asciidoctor

The following gems are only needed if you're interested in also building the documentation (in this repository but also in ALAN Docs) — but to use rake you'll need them too:

gem install asciidoctor
gem install rouge

Asciidoctor will probably complain that some more gems are missing, when you first try to run it, so just install the gems it tells you to (can't remember them all, also it depends on the documentation project you're building).

Updating Ruby Gems

Of course, you'll have to manually update all the various gems from time to time:

gem update

and then, after execute a "clean" command to remove old clutter leftover:

gem clean

ALAN SDK

For this project we're currently using the latest Alpha SDK (development snapshot), because we're using the new UTF-8 source feature which will only be available when ALAN 3.Beta8 is released (fairly soon). When Beta8 is out, we'll be using the Beta version instead.

So you can download the Beta8 build 2268, which is the latest Alpha right now:

• https://www.alanif.se/download-alan-v3/development-snapshots/development-snapshots/build2268

The SDK package for Windows you're looking for is always the one named alan3.0betaX-YYYY.win32.i686.zip (where the X is the next Beta version, and YYYY is the build number), in our case:

• https://www.alanif.se/download-alan-v3/development-snapshots/development-snapshots/build2268/alan3-0beta8-2268-win32-i686-zip?format=raw

From the Zip file, extract the two exe files (alan.exe and arun.exe) and put them on a folder which will be added to your PATH (System or User Path, as you prefer). This way, the compiler and ARun will always be available from the command line, which is what our build scripts (Rake) needs.

• How to Add Executables to your PATH in Windows

(beware that you shouldn't put anything sensitive in that folder, for anything therein will then be globally available).

In the future, when you need to update the ALAN SDK, just drop the new exe files there, overwriting the old ones.

If you also want the graphic version of ARun (for playing and testing manually), download WinARun too (that needs to be installed):

• https://www.alanif.se/download-alan-v3/development-snapshots/development-snapshots/build2268/winarun3-0beta8-2268-win32-i686-setup-exe?format=raw

All these ALAN programs are in 32-bit, so you won't have any issues.

...

Hopefully, I didn't forget anything.

Building the Repo

In any case, if everything is setup as expected, you can then open a command prompt (or Bash for Windows) and just type:

rake

(as long as you're inside a repository subfolder, the command will work).

This will build everything, including documentation (so you'll need Asciidoctor).

To view all the available Rake tasks:

rake -T

To build/update just the Spanish library (doesn't need Asciidoctor at the moment):

rake lib:es:all

Rake will only rebuild files which need to (i.e. if they are missing and need to be built, or if their dependencies have changes), so it's very practical. E.g. if you change a Spanish test adventure, it will recompile only that adventure and rebuild its transcripts, but if you change a library file, then it will recompile Vampiro, all tests, and regenerate all transcripts.

To delete all build files:

rake clobber

To force-rebuild the entire project (even if it didn't change):

rake -B

Pleas let me know if the instructions are clear, and if they worked.

[Rich15]

I installed all gems and the ALAN SDK. I also installed the WinARun and runned one of the adventures that came with the package (the saviour one).

However, I'm still a little confused with Rake. I tried to run the rake command in the alan_es subfolder and it throwed an error:

"alan" no se reconoce como un comando interno o externo,
programa o archivo por lotes ejecutable.
rake aborted!

I don't know if I'm missing something or it's because I don't fully understand Ruby, but if you know what I'm doing wrong, please let me know.

Creating adventures

I understand the adventures need the .a3c extension to be interpreted, but how should I edit them? Using a text editor or IDE? Should I write them first and then pass them to the compiler? I will further study the ALAN syntax to try to make them the correct way, but for now I'm not so clear on how should I start creating them in the first place.

Also, when I create a test adventure I should add it to the tests subfolder and push it to my branch, right?

And again, thanks so much for patiently helping me, for I am pretty new to most of this things and still learning every day :)

[tajmone]

Alan Binaries Not Visible in PATH

I tried to run the rake command in the alan_es subfolder and it throwed an error:

"alan" no se reconoce como un comando interno o externo,

programa o archivo por lotes ejecutable.
rake aborted!

The system is not seeing alan.exe on the system PATH, something must have gone wrong with the ALAN SDK setup. You check that alan or arun are visible to the system, open a CMD (or Bash) and type alan -version, you should get:

>alan -version
3.0beta8 build 2268

and similarly, with arun -version:

>arun -version
3.0beta8 build 2268

Supposing you have put the alan.exe and arun.exe binaries in the folder D:\mypath\, then in the Advanced System Settings » Environment Variables panel you should select Path in User variables for >YourUserName< upper sub-panel, and the click on Edit... » New and just add the folder path (D:\mypath\), at that point the SKD binaries should be visible anywhere in the system — you'll probably have to close and reopen the CMD window for changes to take effect, and on Win 7 even log out and log into Windows again (not sure, worth trying).

(unfortunately, I have no idea what these panels and menus are called in Windows Spanish edition, but you might look it up on Google).

Creating adventures

I understand the adventures need the .a3c extension to be interpreted,

No, ALAN is a real compiler, so the .a3c files are binary files (storyfiles) that need to be run by the ARun interpreter ("interpreter" here doesn't refer to an interpreted language, like JavaScript or Ruby, but stands for "game interpreter"). These files contain the adventure data and code for the AMachine (ALAN's virtual machine), which is like Assembly code.

Editor/IDE

but how should I edit them? Using a text editor or IDE?

You'll need a general purpose text editor that supports Unicode files encoded as UTF-8 BOM (which excludes the AlanIDE, which still needs to be updated to handle UTF-8 BOM in this moment). Ideally, and free editor like Visual Studio Code is good, but also Notepad++, etc.

Alan sources (.alan and .i) and solutions (.a3s) need to be saved using UTF-8 BOM encoding (the BOM is important in this project, since the repository on GitHub will check for its presence in commits and pull requests, to ensure code consistency).

I use Sublime Text 4, but that's a commercial editor (you can try for free without limitations though), for which I also created Sublime Alan IF, an ALAN package (incomplete) that adds some support for the ALAN language. Maybe you could try it, since the ALAN package would make it easier to start working with ALAN.

Should I write them first and then pass them to the compiler? I will further study the ALAN syntax to try to make them the correct way, but for now I'm not so clear on how should I start creating them in the first place.

Yes, you edit the source file and then invoke the ALAN compiler on it, and in this case you'll also need to inform the compiler where to find the Spanish Library files:

alan -include path\to\SpanishFoundation\  YourAdventure.alan

But if you create your adventure inside the \alan_es\tests\ folder of the repository, Rake will handle everything for you — but in this case, you should also add a test script named YourAdventure.a3s, because all adventure in this repository are designed to be tested with a solution file (a solution being a plaintext file containing player commands, one per line).

For more info on using the Alan compiler and interpreter via the command line, see:

• The ALAN Manual » §A.1. Compiling

Also, when I create a test adventure I should add it to the tests subfolder and push it to my branch, right?

Yes. And if you want to create a new adventure (a real adventure, not a test file), just put it in its own folder (like for Vampiro) and I'll add it to the Rake configuration, so it will be tested automatically in the project.

And again, thanks so much for patiently helping me, for I am pretty new to most of this things and still learning every day :)

Don't worry, it's a pleasure (and we all have been there at some point).

[Rich15]

All set

Thanks @tajmone. I had changed the PATH variable but apparently didn't save it, so that was the problem. Now it's done, I tried the compiler with the example adventure on the ALAN manual and it ran well.

I think I am good to go now. I will try to do a short adventure testing the wear verb locally and then commit it to my branch. I have already checked some orthographic and translation issues in some Library Modules, so I'll probably start a pull request shortly.

[tajmone]

Glad to ear that! I'm confident that within a week you'll get the hang of how the repository works — I know that's never easy to jump into an existing project, unlike those who saw it grow from zero.

Looking forward for you PRs!