This post will help you navigate installing and configuring LICH to run on your Mac beast. The overall process is straightforward - but most Mac users who don't code find the process daunting at first, and unfortunately there's too much Googlfied information available to be of much help. These instructions are for non-coders (if you develop on your Mac, I'll answer questions but chances are your environment is set up for your type of development, and these instructions won't apply.)
I am sorry this post is so long. It covers a lot of ground, and I try to do a bit of explaining in case any of you are Googlologists and feel there might be 'other information'. I'd also recommend you make a printout of this post and keep it handy -- if for some reason your computer ever stops working, you will have a hardcopy to refer to about what was done which could assist a pro in troubleshooting (if necessary -- unlikely, but better to be safe, I feel).
Please note that this set of instructions presumes you have not done anything on your Mac OS in terms of installing Ruby, Rubygems or LICH, yet. If you already have, scan the post, but reach out to me if you have problems with your existing install. You probably will not need to do all of this.
Caution -- Simutronics and Gemstone do not warrant or support third party programs like LICH. While these instructions are relatively safe and can easily be reversed if problems occur, understand that by undertaking these steps, you are on your own with only me and other friendly helpful types to assist. Be warned.
We will complete the following steps in order to install / run LICH on your Mac beast:
1) We will download and install Apple's XCode command line tools appropriate for your system. This will come from the Apple site itself, even though there are other ways to download this tool set.
2) We will download and install Homebrew to your system. Homebrew is a 'software bundle handler' which allows us to easily install other software packages on your Mac. There are many variants of these -- Macports, rbenv, and rvm to name some of the more popular ones. But for non-developers, Homebrew is simple and clean with the least restrictions. Hence, it wins as my choice to do this work.
3) We will download and install the latest version of Ruby, so that you get the happy benefit of being able to use LICH version 4.6 and beyond.
4) We will modify your PATH statement so that only when you open the TERMINAL application to start LICH / Gemstone, you will be using the right version of Ruby. We will modify it in such a way that all other computer operations will remain unaffected -- this is important, and perhaps the 'riskiest' of things we will do. But never fear - I will tell you how to do, and also undo if you don't like what you see.
5) We will then confirm the environment is set up properly for our needs. Because versions will vary so rapidly, we'll check to see if we have the right Ruby being called and that its version is greater than 2.0.0, and that the gem environment is set up to use that Ruby.
-- For those of you that read the Mavericks / Yosemite post, from here on out we'll be doing exactly the same things. --
6) We will install the GTK2 gem (version 2.2.0) and the SQLite gem (version 1.3.9).
7) We will install XQuartz program.
8) Finally, we will install Lich, and get into the game! Here, we'll refer to existing information maintained at the LICH website.
That's it! Eight easy steps to success.
A special note: I use CAPITAL case for commands to type into TERMINAL (the application). But you don't need to use CAPS, you can type it in lower case. I simply use CAPITAL letters to make things stand out and make them easier to read.
To prepare, we're going to find out what version of OSX you're using, so we can get the right XCode install process, and we'll cover how to open TERMINAL, the application that will allow us to use command line tools to do our work.
Instructions on how to find out what version of OSX you're using:
| Click on the APPLE menu (upper left hand corner) and select ABOUT THIS MAC |
| Version is displayed as 10.X.X |
| Note version and close window |
Instructions on starting Terminal (the application from which we'll install what's needed, and start the game)
| Click on Spotlight (the magnifying glass in the upper right hand corner) |
| Type TERMINAL |
| Click on the line that says TERMINAL - APPLICATIONS |
| This will give you a white text window that you can type commands in. |
STEP 1: Instructions for XCode Command Line Tools Installation
Sad news! Apple updated its development tools and framework multiple times with each OS version, so you may need to look in the table below for your version of OSX and the click on the appropriate link to install XCode. We'll check to see if you have XCode already installed. In most cases, non-developers will not, so I expect you will not have them installed at this time. You'll need the command line tools (in particular the compiler and various supporting tools) to install other components needed by Lich.
| If you are using Snow Leopard (10.6.8), go right to the note at the bottom of the XCode install section |
| Open TERMINAL if you don't have it open (see above) |
| Type in XCODE-SELECT -P and press the ENTER key |
| If you get a line that starts with /APPLICATIONS or with /LIBRARY, you have the tools installed and may skip the rest of this instruction set. |
| If you do not have XCode installed, type in GCC and press the ENTER key |
| You'll get an Alert Window with three buttons - click on INSTALL (do not click on Get XCode) |
| When the installation completes, click on the DONE button and the Alert Window will close |
Sometimes this process will error out. If you didn't get an Alert Window above, or if you got a specific error message, not to worry; here's what you need to do. This process will take you to Apple's site, and allow you to download a DMG file (the standard way for users to install applications in Mac OSX, and one you probably are already familiar with:
| Do this section only if the previous set of instructions didn't work | No sense in downloading twice |
| Go to https://developer.apple.com/downloads/index.action?=command%20line%20tools | Core site for Mac and iOS Development |
| If you use iTunes or App Store, use your Apple ID to log in | If you don't have an Apple ID, get one - it's free |
| For Mountain Lion (10.8.0 and higher) download the April 10, 2014 file | Click on the title and then click the link on the right to download |
| For Lion (10.7.4 and higher) download the April 15, 2013 file | Click on the title and then click on the link on the right to download |
| For Snow Leopard (10.6.8) - bad news below | Please see the information below for details on XCode for this version of OSX |
Now for the bad news -- you Snow Leopard (10.6.8) beasts have a decision to make. XCode specifically for Snow Leopard was shipped on the 2nd disk of the 2 OS X disk set that came with the original computer. And it's out-dated. Your choices are: You can install from your original disks (but some programs may not compile properly); You can pay $99 to download the XCode 4.2 (the last / best version of XCode for Snow Leopard), or; you can upgrade your system to any other beast for free (except time and aggravation!) I would suggest you at least minimally upgrade to Lion (10.7), and then follow those instructions, but be warned -- you're going to be constantly in danger of slipping off the backside of the Apple support lines. A good guide on upgrading your system can be found here: http://www.tomsguide.com/us/upgrade-snow-leopard-mavericks,news-18388.html
STEP 2: Instructions for Installing Homebrew
Ok, now that that is out of the way, we get to simpler matters. In order to install Homebrew on Snow Leopard (10.6.8) or higher:
| Open TERMINAL if you don't have it open (see above) |
| Copy the following line |
| ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| Paste the line (above) into your TERMINAL window and press the ENTER key |
| This script explains what it is going to do, and will ask you to proceed |
| After the script is done, type BREW DOCTOR in TERMINAL and press the ENTER key |
| You want it to say "Your system is ready to brew." |
| You can ignore warnings about the path -- /usr/local/bin follows /usr/bin -- we'll take care of that later |
| Any other warnings, you should probably cut and paste here or in an email to me just to be sure |
STEP 3: Instructions for Installing the New Ruby
Now we're cooking! This one is pretty short.
| In TERMINAL, type BREW INSTALL RUBY and press the ENTER key |
| Sit back and relax while the build installs |
| You'll see a ton of information on your screen - this is good |
| You may see some warnings fly by - this is neither good nor bad, the process will continue |
| You might see an error fly by - this is bad, and the process will very likely stop |
| If you get an error, copy and paste that error either here or in an email to me before proceeding |
When this process finishes, you'll have a new version of Ruby installed, along with the Rubygems environment. But - your system will still look first to the existing 1.8.7 implementation. So. . .
STEP 4: Instructions for Modifying Your PATH Statement
We will now convince your system that when you're using TERMINAL, it should look for the new Ruby first. This is where the magic happens. We'll do it in such a way so that if Ruby is being called by a process that didn't start through TERMINAL (in other words, all your other operations, including GUI use and automated scripts that the OS uses to maintain itself) it will use the original software. This will save you headache and troubleshooting later on - and some Apple Genius somewhere cursing my name because she spent hours trying to figure out why something wasn't working. There will also be a separate set of instructions on how to reverse this process - just in case.
| Open TERMINAL if you don't have it open (see above) |
| Type CD and press the ENTER key - this makes sure you're in your 'home' directory |
| Type CAT .PROFILE and press the ENTER key |
| If the system output line is "cat: .profile: No such file or directory" we will create this file |
| If the system output line is a bunch of other text, we will modify an existing file and so first we will make a copy of it |
| If we're making a copy of an existing file, copy the following line |
| CP .PROFILE .SAVEPROFILE |
| Paste the line (above) into your TERMINAL and press the ENTER key, and now we can easily recover if we see something we don't like |
| Copy the following line |
| echo "PATH=/usr/local/bin:/usr/local/sbin:\$PATH" >> .profile |
| Paste the line (above) into your TERMINAL and press the ENTER key |
| Copy the following line |
| source ~/.profile |
| Psste the line (above) into your terminal and press the ENTER key (it should look like nothing happens) |
| Now let's test everything - verify that the command worked by typing ECHO $PATH in your TERMINAL and pressing the ENTER key |
| The very first portion of the line should read "/usr/local/bin:/usr/local/sbin" - that's what we're going for |
| If you don't see that at the front of the line, pause and drop me a note in email - we'll have to do a bit of exploring |
What if I don't like the way my computer's operating, and I think this is causing it?
Not very likely, but we can easily take this out of play. Do this if you don't like something about your system or set up and suspect this may have caused it.
| Open TERMINAL if you don't have it open (see above) |
| Type CD and press the ENTER key - this makes sure you're in your 'home' directory |
| Type CAT .SAVEPROFILE in TERMINAL and press enter |
| If the result is a bunch of text, type RM .PROFILE in TERMINAL and press the ENTER key, then type CP .SAVEPROFILE .PROFILE in TERMINAL and press the ENTER key |
| If the system output line is "cat: .saveprofile: No such file or directory", type MV .PROFILE .SUSPECTPROFILE and press the ENTER key |
| Go to the TERMINAL menu (upper left corner) and totally quit TERMINAL |
| Check your system operation and see if this corrected any anomaly you noted. |
STEP 5: Confirming Environment
The home stretch - and short and simple:
| Open TERMINAL if you don't have it open (see above) |
| Type CD and press the ENTER key - this makes sure you're in your 'home' directory |
| Type RUBY -V in TERMINAL and press the ENTER key |
| The system output line should read "ruby 2.X.XpXX" and a date. As long as it's Ruby version 2.1 or higher, this passes |
| Type WHICH RUBY in TERMINAL and press the ENTER key |
| The system output line should read "/usr/local/bin/ruby" |
| Type GEM ENVIRONMENT in TERMINAL and press the ENTER key |
| There will be many lines, but you want to confirm that the RUBY VERSION output line matches your Ruby version from above |
| If there are discrepancies or questions - best to pause and ask them here or in email |
If there are any questions or discrepancies, now is a good time to post them here, or to send me a note. This catches you up to the point that those lucky Mavericks and Yosemite users are at, and now we're all playing the same hymns, so we just continue with those instructions.
STEP 6: Installing GTK2 and SQLite
Instructions for GTK2
Next, we'll install a set of graphic tools that allow Lich to create windows in the Mac environment. This will generate a lot of activity on your TERMINAL screen, and may generate quite a few warnings. Warnings are ok, so don't worry about them too much as long as the process continues. It may generate an ERROR. If it does, it should stop, and you can copy / paste the error here or in an email to me for more help. Pretty good odds that you won't have an error, though.
| Open TERMINAL if you don't have it open (see above) |
| Type in GEM INSTALL GTK2 -V 2.2.0 and press the ENTER key |
| Sit back and relax while the build installs |
Instructions for SQLITE3
| Open TERMINAL if you don't have it open (see above) |
| Type in GEM LIST and press the ENTER key |
| You'll see lines of output that list all Ruby Gems installed on your system |
| Look for a line that says SQLITE (1.3.9) |
| If you have that line, you don't need to install / update and you can go on to the next section |
| If you do not have that line - in TERMINAL type in GEM INSTALL SQLITE -V 1.3.9 and press the ENTER key |
| Sit back and relax while the build installs |
STEP 7: Installing XQuartz
XQuartz is a Mac specfic implementation of the X-window system. It is used by Lich / GTK2 to create those windows for your use in Lich. We will use the more familiar DMG installation method here, instead of the TERMINAL and command line functions. First we'll check to see if it's already installed. And then if not, we'll install it.
| In FINDER, open up your OSX drive |
| Expand the APPLICATIONS folder |
| Expand the UTILITIES folder |
| Look to see if XQUARTZ is listed |
| If you see XQUARTZ, you are all set and you can go on to the next section |
| if you do not see XQUARTZ, go to http://xquartz.macosforge.org and download / install the DMG file there for your OS version |
STEP 8: GAME TIME!
Well, it certainly took us a bit to get here, but here we are. At this point, for Snow Leopard (maybe?), Lion and Mountain Lion users, you now have the environment needed on your Mac to support Lich. You can follow the instructions at http://lichproject.org/download.html for MAC + AVALON + LICH starting at step 4. We've already done all that's required for the first three steps.
Suggestions for EDITS and CORRECTIONS are welcome - please send them to my email, and I'll correct / update as required. I'll post this to GSWIKI after about 30 days, when I get past initial corrections requested.
Doug
