anton.maurovic.com

AMMAURO #2: Linux VM for developers

2017-01-02T00:00:00Z

My 2nd video in the AMMAURO series shows how Windows and macOS (OS X) users can install a Linux virtual machine to help supplement their development environment, and get the most out of all platforms.

AMMAURO #2 - Linux VM under Windows or macOS to enhance your development

It’s been a long time since my last post, and my last video in the AMMAURO series. This new video lays the foundation for future videos about electronics design and experiments, hardware development and hacking, and software development. It shows you how you can (and maybe even should) keep running your existing Windows or macOS desktop development environment, but also leverage the full power of Linux in that same environment, using a VM (Virtual Machine).

NOTE: Step 6 in the video refers to instructions and commands to install some essential packages, which I’ll repeat below for your convenience. Please note that the following were taken from https://github.com/pfalcon/esp-open-sdk…

Run the following for Ubuntu 14.04 and above:

sudo apt-get install make unrar-free autoconf automake libtool gcc g++ \
  gperf flex bison texinfo gawk ncurses-dev libexpat-dev python-dev \
  python python-serial sed git unzip bash help2man wget bzip2

…and for newer versions of Ubuntu you may also need to run:
```
sudo apt-get install libtool-bin
```

From time to time you will hopefully see me post new videos on my YouTube channel.

If you’d like to comment – say, with feedback, requests, or suggestions – the best way will be via the YouTube comments of each video.

My First YouTube Video: Inkjet Printer Teardown

2014-05-11T00:00:00Z

I made a YouTube video. I plan to make a series of them. It will mostly just be about electronics stuff, and pretty random at that. Will it make me rich and famous? Probably only “a bit”.

AMMAURO #1 - Inkjet Printer Teardown

Here’s a video in which I take a grimy old inkjet printer that I found on the side of the road, and tear it down to see what parts I can salvage from it:

This is my first attempt at creating a YouTube video. From time to time you will hopefully see me post new videos on my YouTube channel. They’ll likely all focus on electronics, hacker/maker stuff, and maybe other science and technology. All of my videos of this ilk will be marked with the “AMMAURO” prefix.

If you’d like to comment – say, with feedback, requests, or suggestions – the best way will be via the YouTube comments of each video.

Good News! Feel good with positive news websites

2014-01-26T00:00:00Z

Since I no longer subject myself to daily news, I’m happier. It takes an attitude shift to stop indulging in gossip and the likes of “current affairs”, Facebook, newspapers, and the general doom and gloom of modern journalism. Having said that, I still need to know what’s going on in the world. If you want a better outlook but still need to stay informed, then I have good news for you…

No news is good news
Good news is better news
Positive news sites worth checking out
Lesser-quality positive news sites
Sites to avoid
Conclusion
See Also

No news is good news

"BEST from news"? Really??

As a child I respected what I understood to be “the news”. Adults seemed to rely on it for stories of greater human importance, of world-wide relevance, of intelligent meaningful facts, and of cultural enrichment. I assumed that some day it would help me to make important decisions, and otherwise shape my life for the better. As I grew up, though, my perspective changed. In particular, a couple of years ago, I noticed something interesting…

Frequently my job has required that I work on others people’s computers. I’d launch their web browser, and be presented with the system default homepage. To be specific, it was mostly “ninemsn”, and something on that page would inevitably catch my eye. Before I knew it, I’d be robotically clicking through news articles, and brooding.

I say “news articles”, but more often I’d be poring over articles covering: the stupidity of Stereotype A; the absurdity unfolding amongst Minority B; or what Teacher C had been doing to Student D with object E under circumstances that seemed wholly un-curricular. And then I’d get angry – at humanity, at the world, at life, at myself for wasting time – but the clincher was when I realised I was more angry at the site for making this readily available to me. It was insulting too, that I was probably just being manipulated anyway.

I decided to stop paying attention to mass-media, which at first was difficult; it’s all around in one form or another. I’d become addicted to being incensed by society – as though my outrage reinforced that I was a better person and deserved more out of life than others.

After a while, though, I became apathetic to keeping up with current events and I felt happier. I didn’t so much like the sense of being ignorant, though. I needed to be informed somehow, so what could I do?

Good news is better news

It stands to reason that if you’re immersed in an environment dominated by negative views, then you’re likely to become negative yourself. A negative environment drags you down, and we’re all inclined to sway with that pack mentality. This is not to say that wearing rose-coloured glasses is a solution. Rather, one should have a healthy mix of reality to keep informed, positive, and appropriately impassioned all at once. With this in mind, I set out to find some sources of positive news on the Internet, using the following as a makeshift set of guidelines for assessing any candidate sites:

An ideal site should:
1. Have truthful, important stories from around the world;
2. Show alternative positive views on current negative topics;
3. Suitably present the specific importance of serious/grave issues to its audience;
4. Present researched and moderated content of high quality, with intelligent, adult writing;
5. Show suitable respect to the people covered in its stories;
6. Balance important world-stage news with uplifting, forward-focused stories.
7. Really be worth sharing.
An ideal site should NOT:
1. Promote any particular interest, political view, cultural view, or religious standing;
2. Sugar-coat anything;
3. Resort to hyperbolic headlines to get attention, or any other link baiting;
4. Present an idealised substitute for reality;
5. Show a preoccupation with hollow celebrities;
6. Take an elitist view, or otherwise try to exclude a willing audience;
7. Make a spectacle of the suffering of others.
8. Function as promotion for a news service that shamelessly profits from negativity, or from manipulating people’s views.

A quick Google search for “positive news sites” turned up a lot of results and it seemed it should be easy to find some that would meet at least most of the criteria above. However, as I started working through the list, my optimism faded somewhat. At best, most sites seemed to be little more than a blog, and really didn’t feel like true journalistic outlets at all.

Nevertheless I persevered and my findings are interesting…

Positive news sites worth checking out

OdeWire – http://odewire.com

I was impressed with this site. By the time I came across it, I had been through a dozen poor-quality “good news” sites, and I was ready for the fresh, balanced perspective that OdeWire provides. As a site maintained by The Intelligent Optimist magazine (formerly “Ode Magazine”), it does not simply avoid bad news and pile on feel-good filler. Rather it offers a stream of realistically objective stories that seem to be hand-selected from many reputable news outlets around the world. To quote a recent article of theirs:

Optimism has nothing to do with ignoring reality and denying the bad hands that life often deals us.

The site’s tagline of “News for Intelligent Optimists” appears to be backed up by good content. There seems to be an even mix here: Encouraging positive stories are interspersed with reports of serious world events, presented in a way that is both informative and mature. Reading through this site gives me a sense that I am participating in something intelligent and important, that really is news, while maintaining a sense of calm and neutrality.
Positive News – http://positivenews.org.uk

“Positive News” claims itself as “the world’s first positive newspaper”, and is another site which seems to be professional in its presentation and writing, while staying true to its message. Amongst its benefits are that it has an accompanying newspaper in print and it has a strong community involvement. As a publication of the Positive News Trust charity, its staff largely comprise young volunteers, including up-and-coming journalists who have an opportunity to gain valuable experience.

The overall quality and value of the stories is generally pleasing, with world-wide relevance (including Argentinian and Spanish counterparts). There is an even spread of detailed reports of higher importance, as well as shorter stories that are up-lifting and motivational, while remaining relevant and down-to-earth. If you benefit from the site, or at least believe in their purpose, you are encouraged to make a donation at the end of each article.
Global Good News – http://www.globalgoodnews.com

This one may surprise you, as it did me. When I saw it I nearly abandoned it, for two reasons: (a) its visual presentation seems to be very “tacky”, for want of a better word; and (b) there is an overt religious aspect, which often means you can expect the journalistic integrity of the stories to suffer. Despite this, though, the stories themselves seem to actually be of high quality, with perhaps the highest number of new stories per week of any other sites I’ve reviewed.

As an Australian, I was pleased to see at least a couple of stories on the first page that were highly relevant to me. The same seems to be true for readers from many other countries, particularly with an Arabic counterpart. I have seen perhaps the most diverse range of cultures and demographics represented at this site, making it live up to its “Global Good News” name. As with the other two examples above, this site features mature, intelligent articles that are meaningful and informative.
Optimist World News – http://optimistworld.com/News.aspx

This newsfeed is actually part of a larger site called Optimist World, which aims to inspire its readers and promote goodwill in general. The site as a whole has a friendly and polished appearance, giving it a more-youthful feel.

Articles at Optimist World are well-written and easy to read for all ages. They give a sense of light-hearted satisfaction, without being immature or saccharine. My only criticisms are that: (1) the articles seem to have more of a Western focus with less attention to important world-wide events; and (2) compared to other sites, it is not updated all that frequently. Other than that, it is definitely worth a read from time to time.

Lesser-quality positive news sites

Finding high-quality positive news sites is difficult; the ones given above stand out of the dozens I inspected. Most of the rest are a little cheesy (especially when there’s a religious message involved), or simply have a very amateurish “blog-like” feel and are unashamed about manipulating you to wander aimlessly through their pages to generate advertising revenue.

While the following sites don’t meet as many of my key criteria, I can at least commend them for the positive impact they aim to provide. There are many sites that follow in the style of these, so I’ve only listed a handful. Search around, and you may find some that really appeal to you or otherwise contribute further value in your daily quest to be optimistic.

Gimundo – http://gimundo.com

This one pops up a bit in other people’s recommendations for Good News websites. While it has a nobile purpose, like many of the sites I list here, I find it to be a little weak overall. The site is not updated very often, which is more of a problem given that the articles are not particularly important or relevant. The stories seem to have a strong focus on the USA, with subjects and headlines that are selected specifically to snare your clicks (and hence push more ads). Gimundo is fine if you’re looking for a quick pick-me-up, but beyond that has limited intellectual appeal.
Sunny Skyz – http://www.sunnyskyz.com

As with Gimundo, this site and its “Good News” newsfeed do meet their targets of being positive, but also like Gimundo the stories are a bit thin, and the professionalism a bit sparse. The site is easily-accessible and has a lot to offer, but most of what it offers is again designed to snare clicks and just keep you browsing. What this leads to is hyperbolic headlines (e.g. “This is amazing. You have to see this…” and “Incredible thing happens. Watch the video!” without qualification), very short stories loaded with pictures, and topics that are not overly important or realistic. This is fine if you have nothing better to do, but I get about as much intellectual satisfaction from an article on this site as I do from reading a proverb inside the lid of a fruit juice bottle.
Good News Network – http://www.goodnewsnetwork.org

Here’s another site which seems to feature prominently, but doesn’t impress me much. It suffers from mostly the same problems as the other examples given above, though I can at least credit the fact that it “feels” more like a news site and provides a frequent stream of stories that have intellectual appeal without being too sugar-coated. Still, those stories are often thin, and have a heavily American focus from what I can tell.
Happy News – http://www.happynews.com

The articles at this site are fine, if a bit light. Few of the stories are what I would call “news”, in that they are not particularly ground-breaking or relevant to current events, and are more of what you’d expect from a blog. That’s OK, and I commend the fact that they are informative and are presented well with meaningful, mature headlines. I’d almost bump this site up to the list of better sites worth checking out, except that at the time of writing, Happy News hasn’t been updated for at least 6 weeks; the most recent article is dated October 16th, 2013.
Great News Network – http://www.greatnewsnetwork.org

This site is reasonably good, with meaningful stories presented in a mature way. It’s worth reading, and has value overall. The only problems with it are that the presentation is very basic, there’s slightly too much focus on US stories, and it is infrequently updated. Besides that, though, I’d suggest you keep an eye on it.
Wonderful World (NBC News) – http://www.nbcnews.com/id/13282721/

Here we start to get into the curiosity that is major news outlets trying to capitalise on a growing interest in positive news. There are some cases where this really becomes farcical (and we’ll see a couple below), but NBC News’ “Wonderful World” section isn’t too bad. It’s quite glorified with an almost exclusive focus on American stories, some of which are a bit on the banal side, but at least NBC News seems to be trying to maintain some sense of integrity, which is more than I can say for the following examples. Doesn’t it deserve a nicer URL, though?

Sites to avoid

I see the sites below as ones you should avoid because they really miss the mark overall. They rarely offer anything original or of value, often have infantile headlines designed to catch clicks, and besides failing on many of my guidelines they are often shameless commercial exploitations being peddled by the major news networks. All in all, these will waste your time, do nothing to inform you on the world stage, and offer nothing intellectual.

HuffPost Good News – http://www.huffingtonpost.com/good-news/

This site stands out as the only “good news” site that makes me actually angry. The stories are trite, and heavily American. The presentation is childish; categories such as “AWW” and “OMG”, with endless hyperbolic headlines, really insult my intelligence. The cluttered noise of links begging you to click everywhere really cheapens this site by highlighting how they don’t care what you do, so long as you see as many ads as possible.

All that aside, the one thing which openly infuriates me is that a big chunk of the page – one third of the right-hand side of the first few screenfuls – is dedicated to stories from the rest of Huffington Post. These are almost always horrible or at least highly negative, and tailored to enrage.
Good News (ABC News) – http://abcnews.go.com/US/Good_News/

Unlike HuffPost, above, this site is not terrible. There are some key things about it, though, which mean it won’t be part of my daily hunt for positive news. Besides failing to meet several of my guidelines, it is a little too focused on America, and – as seems to be typical of the major news sites now – relies far too much on video content. This is incredibly frustrating, as I often want to read articles (especially during a quick break at the office).

What’s more frustrating is that the video stream seems to start, run, and roll on to the next article all on its own, each time playing the same annoying ad before each brief “news” segment. At first I loaded up several stories as separate tabs, in advance, expecting to read each one in turn. Instead, I heard one ad fire up three times with overlapping audio, while my browser started to grind to a halt, trapping me in an endless Orwellian spiel about baby oil.
Feel Good News – http://www.feelgoodnews.com

This really isn’t what I’d call news. It’s just YouTube videos. Some may be from commercial news networks, but most are just mental “candy” with footage of babies, animals, and minor thrills. This is highly un-informative, and we can get an endless stream of this sort of stuff from anywhere.
DarynKagan.com – http://www.darynkagan.com

I don’t really know who Daryn Kagan is, and though I suppose she deserves some recognition for what appears to be a personal plight to bring positives stories to the fore, I am not overly impressed with her website. Measuring it by my guidelines, it misses the mark a bit, largely just linking to the same sort of unimportant “filler” videos found on all of these low-quality sites.

Conclusion

"...but it IS ready to shoot right up!"

While it may be difficult for some of us – maybe most of us – to avoid being emotionally manipulated by big business and especially Big News, we can take measures to avoid its triggers and traps. This can, at times, be an effort or even inconvenient in this modern world saturated in advertising, social media, endless immediately-accessible information, and commercial entertainment. Nevertheless, time out is an important thing. There’s a lot to be said for going off the grid occasionally, and just experiencing the world for yourself.

If you MUST be subjected to negativity, try to find something to balance it, in the realm of good news. There is actually a lot of good news to be found; times may not actually be so bad as what the relentless thrust of negative news would otherwise have us believe. When you do find something genuinely and valuably good, share it, and do so in an intelligent way. Feel free to share with me, too!

Nintendo (NES) Gamedev, part 1: Setting up

2013-11-10T00:00:00Z

This is the first article in a short series on throwing yourself quickly into learning game development for the Nintendo Entertainment System. The idea will be to get quick results by example, while learning some key details of how the platform and development tools work.

Introduction
NES Development Environment
Testing your emulator
Testing cc65 by building example code
Conclusion
Appendices

Introduction

I love the aesthetic of classic videogames, and the technical oddities of their platforms. I got into game development for the NES (Nintendo Entertainment System) to understand and enjoy these aspects more, but also for the challenge and skills to hopefully ready me for some related future projects.

After reading a lot of articles I really just wanted small examples that did something useful, while explaining them well. While there are many tutorials on game development for the Nintendo Entertainment System, my objectives in this short series will be to help you quickly get an environment going, build some very basic examples, try them out, and then expose exactly what’s going on.

In this first article, I cover the bare essentials for Windows, Mac OS X, and Linux. That is, a means to compile code that targets the NES, and a way to see that code running on your PC. At the end of this article, you will compile and run some example code to prove that your environment works. This will set the stage for fun stuff starting in the next article, when it is ready.

NES Development Environment

Of all the PC-based tools you may use when developing for the Nintendo Entertainment System, these are the essentials:

A compiler/assembler. I strongly recommend the cc65 cross-compiler/assembler for the 6502 CPU. It is very well-written, highly configurable, and available for Windows, Linux, and Mac OS X. Future articles will focus on how to use it effectively.
A NES emulator¹. With an emulator, any NES-format files you create can be run directly on your PC – much as they would run on a real NES – for quick testing. Some emulators are better than others at precisely emulating all known features (and quirks) of the real NES hardware. A handful of emulators offer inspection and debugging features, too.

Choosing an emulator depends on your platform, but for now I recommend FCEUX as it is available for Windows, Linux, and Mac OS X. Note that while it has excellent debugging features in the Windows version, disappointingly these are absent from the Mac and Linux versions at this time. See the alternative software appendix below for other compilers and emulators, but note that this article focuses on cc65 and FCEUX.

In the instructions below, I show you how to install both cc65 and FCEUX, under Windows, OS X, and Linux.

Installing on Windows

First, we install FCEUX:

Go to the FCEUX download page, download the “FCEUX win32 Binary” (I used the latest available at the time, 2.2.2), and extract it. It has no installer, so just place the extracted files wherever you like, and run fceux.exe to test that it launches.
Make sure the location where you placed fceux.exe is added to your system PATH, because you will usually want to launch compiled files with FCEUX, directly from your command-line.
Then, we install cc65:

Download the cc65 installer. You’re looking for cc65-2.13.3-1.exe or similar. I went to the original cc65 FTP site and downloaded cc65-2.13.3-1.exe but that may be closed down at some point. If so, mirrors are available.
Launch the cc65-2.13.3-1.exe installer, and perform a default install.
Verify that it has installed by bringing up a new Command Prompt and running:
```
> cc65 --version
cc65 V2.13.3
SVN version: 5495
```

Now you can proceed to the ‘Testing your emulator’ section.

Installing on Mac OS X

These steps rely on Homebrew to install both cc65 and FCEUX. You can alternatively compile the latest source for cc65 and FCEUX, but that’s the hard way to go about it.

Make sure Homebrew is up-to-date, and that its environment is set up correctly:
```
brew update
brew doctor
```
Install the cc65 package:
```
brew install cc65
```

Test:

$ cc65 --version
cc65 V2.13.3
SVN version: unknown

Next we’ll install FCEUX, but please note that FCEUX requires an X11 environment. If you have OS X 10.7 or below, then you already have X11.app built in, and there’s nothing you need to do. If you have OS X 10.8 (Mountain Lion) or above, Apple recommends installing XQuartz.
Now install the fceux package, which for me took about 40 minutes due to all the extra packages required to build it on OS X:
```
brew update
brew install homebrew/games/fceux
```
NOTE: Previously, FCEUX could be installed with just brew install fceux, but the package has been removed from the standard Homebrew set.

Now you can proceed to the ‘Testing your emulator’ section.

Installing on Linux

So far I have only attempted to install cc65 and FCEUX on Ubuntu 12.04 LTS (64-bit), where I rely on APT (i.e. apt-get, as used by Ubuntu and Debian). I also have an appendix for instructions to compile cc65 and FCEUX on Linux. If you have reliable and complete instructions for other platforms, please let me know.

First we install cc65:

Spiro Trikaliotis has prepared, and hosts, an APT repository that can be used to install cc65 as a Debian package. To use it, first make sure you have debian-keyring installed.
```
sudo apt-get install debian-keyring
```

Add the key for Spiro’s repository:

# NOTE: Sometimes this server can take over 90 seconds to respond:
gpg --keyserver wwwkeys.pgp.net --recv-key 2AF47E44
gpg -a --export 2AF47E44 | sudo apt-key add -

Add Spiro’s repository to your APT sources, by editing /etc/apt/sources.list and adding the following lines at the end:
```
deb     http://debian.trikaliotis.net/ stable contrib
deb-src http://debian.trikaliotis.net/ stable contrib
```
Update your APT sources:
```
sudo apt-get update
```

Install specifically² version 2.13.3-1 of cc65 and cc65-nes:

sudo apt-get install cc65=2.13.3-1 cc65-nes=2.13.3-1

Check cc65:

$ cc65 --version
cc65 V2.13.3
SVN version: 5401

Now we install FCEUX:

First, make sure curl and unzip are installed, as they will come in handy later:
```
sudo apt-get install curl unzip
```
Install the fceux package:
```
sudo apt-get install fceux
```
…which, at the time of writing, installs specifically version 2.1.5+repack-0buntu1 on Ubuntu 12.04.

Now you can carry on into the ‘Testing your emulator’ section below.

Testing your emulator

Download a NES ROM package file (i.e. a .nes file) from somewhere, and launch it with fceux. For example, grab the free BombSweeper, extract the file, and launch it.

On Windows, just download the file and extract it. Then go into Command Prompt, and into the directory where you extracted it, and you should be able to launch it with:
```
fceux BombSweeper.nes
```
On Mac OS X and Linux, you should just be able to do:
```
curl -Lo bombsweeper.zip http://www.zophar.net/download_file/11839
unzip bombsweeper.zip
fceux BombSweeper.nes
```
You will probably want to scale the display, so go to FCEUX’s video configuration and set both the X and Y scaling factors to 2.0 (or maybe even 3.0).

On Windows, go to the ‘Config’ menu, select ‘Video…’ and change the ‘Size Multiplier’ fields:

On Mac and Linux, you need to go to the ‘Options’ menu and select ‘Video Config’:

Testing cc65 by building example code

Though I won’t get into explaining NES coding concepts until the next article in this series, we should at least grab some example code now and make sure it compiles and runs.

I have set up a public GitHub repository (algofoogle/nes-gamedev-examples) which will be fleshed out with example source code corresponding to each article in this series.

Grab my nes-gamedev-examples repo:
```
git clone https://github.com/algofoogle/nes-gamedev-examples.git
```
Alternatively, you can direct-download the master branch as a ZIP file, and extract it.
In your shell/command-prompt, go into the part01/ex01-c-example directory, which is source code in C that displays a simple message and plays a tone.
Build it with cc65 (specifically the cl65 “compile-and-link” tool) as follows:
```
cl65 -t nes hello-nes.c -o hello.nes
```
Try launching the resulting hello.nes file with FCEUX:
```
fceux hello.nes
```
NOTE that I’ve sometimes seen on Mac OS X that FCEUX will take a long time to properly launch if X11 is not already running. If you’re on OS X 10.7 or below, you can launch X11 in advance with:
```
open /Applications/X11.app
```
…and there would be an equivalent for OS X 10.8 and above with XQuartz.

NOW we will try assembling an example written in 6502 assembly language:

Go into the the part01/ex02-asm-example directory of the repo.
Assemble the test.s file, with:
```
ca65 test.s
```
…which produces the test.o object file.
“Link” the object file into a .nes binary file, with:
```
ld65 test.o -o test.nes -C nesfile.ini
```
Try launching the resulting test.nes file with FCEUX:
```
fceux test.nes
```

Conclusion

So, where to from here? You now have a way to take raw source code and build a .nes file from it, that can then be played on your PC in a Nintendo Entertainment System emulator.

You can have a go at figuring out what’s going on in the example source code if you like, but some of it is quite complex and counter-intuitive, so don’t feel bad if it just gives you a headache.

In my next article I intend to explain what a .nes file actually is and how cc65’s build process (and configuration) works. Then I’ll start explaining the core code found in every game for the Nintendo Entertainment System. I’ll begin with much simpler examples (that also uncover key 6502 assembly concepts), and work up through essential features of a minimal functioning NES program.

If you’re keen to get on with it, though, you might want to read the following:

Good luck, and see you next time!

Appendices

Each appendix here is provided in case you are having trouble with installing cc65 or FCEUX, or for those who want to try out alternatives to the process I’ve recommended above. You don’t need to read any of this if you have successfully completed the above build-and-run test.

Mirrors of cc65

At the time of writing, the latest version of cc65 is maintained by Oliver Schmidt, at the new cc65 website. The latest source code is available via Oliver’s cc65 GitHub repo, and is still actively maintained.

In principle, you can find everything you need via: the new cc65 website; the new cc65 Wiki pages; and the cc65 GitHub repo. This includes instructions for building on Windows, where you may prefer (or need) to take the 2nd option (“Use prebuilt cc65 binaries”) rather than compiling those binaries yourself – so long as you first install “Make for Windows” as described on that page.

I, however, was lazy and opted to just download the cc65-2.13.3-1.exe installer for Windows. This can can be obtained (with the source code, amongst other things) from any of the following mirrors:

I also have my own copy of all the files; if you’re really stuck, contact me.

Building cc65 and FCEUX from source on Mac OS X

Be warned: Compiling cc65 is easy enough, but compiling FCEUX on OS X may be painful. Installing with Homebrew is strongly preferred. Otherwise, proceed with caution.

Building cc65 on Mac OS X

Make sure you have git installed. If not, see: Set Up Git.
I assume you will keep all your projects in a folder called projects in your home directory. So, following this, go into Terminal and:
```
mkdir -p ~/projects
cd ~/projects
```
Use git to clone the https://github.com/oliverschmidt/cc65.git repository:
```
git clone https://github.com/oliverschmidt/cc65.git
cd cc65
```
You now have the source code for cc65. Simply build it with:
```
make
```
If it fails straight away on this make command, you probably need to install the Xcode Command Line Tools.

If you do have a working make, it will spew a lot of information as it compiles all the source files and builds the final binaries. In my case it also gave a warning at the end:
```
ar65: Warning: Library `../lib/supervision.lib' not found - will be created
```
…but this can be ignored.

Do a test run:

$ bin/cc65 --version
cc65 V2.14.0
cc65: No input files

Now install it system-wide:
```
sudo make install
```
OR if that doesn’t work, try this instead:
```
sudo make avail 
```
…and the binaries (cc65, ca65, etc) should now be found in (say) /usr/local/bin.

Test again:

$ cc65 --version
cc65 V2.14.0
cc65: No input files

You should also ensure you have the CC65_HOME environment variable set to the path which contains your cc65 binaries. You can add this, for example, to your ~/.profile (or, if you already have a ~/.bash_profile file, add it to that instead; ~/.bash_profile overrides ~/.profile):
```
echo "export CC65_HOME=$(dirname `which cc65`)" >> ~/.profile
source ~/.profile
```

Building FCEUX on Mac OS X

If you have OS X 10.8 or above, you will need an X11 environment to build and run FCEUX. Apple recommends installing XQuartz in this case.

Apparently, building FCEUX on Mac OS X is not exactly easy. There are a lot of depenencies required, and many people end up managing these dependencies with Homebrew, MacPorts, or Fink anyway.

I’ve found that ConsoleEmu.com – despite occasional page load errors³ – has builds of FCEUX for Mac OS X (with more recent ones at the bottom). Note that I can’t vouch for how good these are, as I haven’t tried them out. If you do have success with them, please let me know, including anything that you had to do besides just extracting and launching.

Anyway, if you are determined to build FCEUX on Mac OS X, you may find the following links helpful:

Official FCEUX build instructions for OS X;
Some tips on building FCEUX on Mountain Lion;
FCEUX Homebrew formula code and original announcement, which may give you some tips on how a working build process can be achieved.

Building cc65 and FCEUX from source on Linux

I only tested this lightly, from a fresh install of Ubuntu 12.04 LTS (Precise Pangolin) 64-bit. I did the following:

Update APT sources:
```
sudo apt-get update
```
Install git and make:
```
sudo apt-get install git make
```

Grab the cc65 repository:

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/oliverschmidt/cc65.git

Build cc65:
```
cd ~/projects/cc65
make
```
Install cc65:
```
sudo make avail
```
Test:
```
$ cc65 --version
cc65 V2.14.0
```
Now, when it came to building FCEUX on Linux, I didn’t bother trying. Hopefully you will find adequate instructions via one of the following:
- Jack David Baucum’s instructions for building FCEUX on Ubuntu;
- The Homebrew formula for building FCEUX.

Alternative Software for NES Development

I won’t keep these tables up-to-date. Hence, the “Version” and “Last updated” columns may fall behind the actual latest versions.

Below, I have listed some alternative software you can use for assembling NES-targeted 6502 assembly code, as well as alternative emulators for running .nes files. I certainly haven’t done any sort of review of the information below; I have tried to dig around and find out a little bit about each package, but I haven’t really tried any of them out.

NOTE: I’d like to give special mention to NESICIDE, which is a new NES IDE (Integrated Development Environment). It has been in development for some time and hopes to combine several NES development tools into one package. The plan is that it will comprise a source editor, emulator, compiler/assembler, debugger, and graphics/sound editor. It looks promising, but development on it seems to have slowed, and most features are so far only available for Windows; not so much for Mac OS X and Linux. Keep an eye on it, though, and maybe you feel like contributing to the project, or making a donation?

Alternative 6502 assemblers

Product	Version	Last updated	Win?	Mac?	Linux?	Source?	Notes
cc65	2.14.0	2013-10-18	YES	YES	YES	YES	Includes C compiler, and config targeting many 6502 systems.
ASM6	1.6	2010-11-03	YES	No	No	YES⁴	Releases of ASM6 are ad-hoc, not “managed”.
NESASM3	3.1	2011-01-08	YES	No	Yes?⁵	YES	Simplistic, NES-specific. Focus of “Nerdy Nights” tutorials.
DASM	2.20.11	2008-09-22	YES	Yes?	Yes?	YES	Targets multiple platforms and other 8-bit CPUs.

Alternative NES emulators

Product	Version	Last updated	Win?	Mac?	Linux?	Source?	Notes
FCEUX	2.2.2	2013-09-23	YES	YES	YES	YES	Debugging excellent in Win, but absent from Mac/Linux.
Macifom	0.16	2011-09-27	No	YES	No	YES	Native Mac app with `.dmg` available. Basic debugger.
Nintendulator	0.970	2013-04-23⁶	YES	No	No	YES	Good debugging tools. Trying for high-accuracy.
Nestopia	1.45	(Various)	YES	YES	YES	YES	See below for more info.

Nestopia versions

Nestopia was originally (?) a Windows-only NES emulator, but there have been different forks of it to support Linux and Mac OS X also.

The original Windows version of Nestopia is 1.40, and since 2008 has been abandoned. It can be found on the Nestopia downloads page along with source code.
A Mac OS X version (1.4.1), from September 2008, is available via Richard Bannister’s website.
It seems rdanbrook (aka 0ldsk00lca) has taken over creating more-recent versions of Nestopia, which is up to version 1.45:
- A Windows binary is available.
- Source code is available via GitHub.
- There are packages available for installing on Debian, Arch Linux, and OpenBSD.

While this article focuses on PC-based emulation for testing, in a future article I will demonstrate making a basic reprogrammable cartridge (“GamePak”) that can be used in a real NES.↩
I found that if I did a default install with sudo apt-get install cc65, it would install a more-recent (unstable?) version: 2.13.9-svn5990-1. This seems to have a problem where it reports the following errors when I try to target the NES using C source:
```
$ cl65 -t nes hello-nes.c -o hello.nes
Unresolved external `doneirq' referenced in:
  callirq.s(41)
Unresolved external `initirq' referenced in:
  callirq.s(40)
ld65: Error: 2 unresolved external(s) found - cannot create output file
```
↩
At the time of writing, links within ConsoleEmu.com are coming up partly blank, or reporting 404 errors. I’ve noticed that it sometimes appends a PHP Session ID (e.g. ?PHPSESSID=44baf3d2xxx8b610e3b) on some URLs, and these seem to screw up its internal link parsing. In those cases, I just remove this suffix (including the question mark), and it seems to work.↩
Source code for ASM6 is supplied as a single C file, along with the ASM6 binary, in the downloadable ASM6 archive.↩
This article on NintendoAge suggests, in the “ASSEMBLERS” grid, that NESASM3 is available for Linux. It’s not clear whether you just have to compile it for Linux yourself from the source which appears to be managed as a Dev-C++ project.↩
The “current release” (0.970) is from 2010-01-02. The Downloads page for Nintendulator has a sub-heading describing the “Latest unstable build” which, at the time of writing, is 0.975 Beta, last updated on 2013-04-23. Latest source is also available, as well as source code for the mapper DLLs.↩

Simple but Delicious Nasi Goreng

2013-10-20T00:00:00Z

Nasi Goreng is Indonesian fried rice. This variation is quite simple, with the main flavouring ingredients being only bacon, onion, mushroom, and a few basic spices. Despite that, it is quite delicious and filling, and quick to prepare.

Serves: 4
Preparation time: 10 minutes
Cooking time: 20 minutes

Nasi Goreng is an Indonesian dish, with “nasi” meaning “rice” and “goreng” meaning “fried”. The recipe here has fewer ingredients than is traditional¹, making it simpler and more-economical, as well as faster to prepare. I have always loved this one as a kid, as it is very moreish, with excellent flavour and aroma. It’s a good base for adding many other things that may take your fancy, too.

Ingredients

Main recipe:
- 2 large onions
- 6 rashers of middle bacon
- 8 medium mushrooms
- 3 tbsp butter
- 1½ tsp curry powder
- 1½ tsp paprika
- ½ tsp chilli flakes
- 4 tsp vegetable stock powder
Rice:
- 3 cups basmati rice
- 3 cups water

Method

Dice the onions and bacon.
Dice the mushrooms into a separate bowl.
Melt the butter in a frying pan on high heat.
Gradually fry all of the onion and bacon, until it is just starting to brown. This will take about 10 minutes.
While frying the onion and bacon, start steaming the rice. With a typical rice cooker, 3 cups of water is enough to ensure the rice doesn’t go mushy.
Stir in the diced mushroom.
Add all of the spices and vegetable stock to the frying pan, stirring it around thoroughly as it cooks. Using a wooden spoon or spatula, keep dislodging ingredients that congeal and stick to the frying pan.
After about 5 minutes, the contents of the frying pan should be a deep golden-brown colour. The fragrance of the spices should now be more blended.
When the rice is cooked, stir it in to the frying pan, and set it to medium-low heat.
Keep stirring it around for another 5 minutes as the mixture combines, turning the rice an even yellow-golden colour.
Serve!

Variations

The definition of “Nasi Goreng” is very broad, so you can add just about anything you like to it. Here are some suggestions for how to mix up the recipe a bit:

For a more-lean variant, replace the butter with an oil, such as a couple of tablespoons of olive oil.
Try using less bacon, and more chicken. Dice the chicken and cook it with the onions and bacon from the start, or marinade chicken tenderloins and cook them alongside the main recipe, adding them in at the end.
Substitute ziti, penne, or macaroni pasta for the rice. This was also a favourite of mine, as a kid.
If you’re looking to cook a larger quantity, you may find it easier to stir in the rice if you started preparing the dish in a wok or electric frying pan.
Try the more-traditional ingredients and garnishes. For example, check out this Nasi Goreng recipe.

According to Wikipedia, a key ingredient in traditional Nasi Goreng is sweet soy sauce. Other common ingredients include: garlic; shallot; spring onions; nutmeg; turmeric; palm sugar; and ginger garlic paste.↩

Mac OS X Development Environment with Ruby

2013-10-12T00:00:00Z

As a programmer it helps to be comfortable across many different platforms, and learn to leverage the benefits of each. After purchasing my first Mac – an old MacBook – I set out to create a tailored environment that would help my Ruby (and other) development sing.

Summary
Checking existing environment
Installation Steps
Install optional stuff
Other stuff worth checking out
Troubleshooting
Tips for installing on Mac OS X 10.8 and above
Installing Xcode CLT via command-line
Conclusion

Summary

There are lots of options for setting up a development environment on a Mac, and even more options for the Ruby side of things. Starting with a clean install of Mac OS X 10.7 (Lion), in this case, I worked out the best combination of development tools to suit my needs. While these lean towards Ruby, they should be a good baseline for other development needs.

UPDATE - 24 January 2014: I have since tested these instructions on Mac OS X 10.8.5 (Mountain Lion) and made some minor edits to ensure that both OS X 10.7 and OS X 10.8 are covered. Particular revisions for OS X 10.8 are covered in: Tips for installing on Mac OS X 10.8 and above.

Here’s a summary of the choices I made:

Mac OS X 10.7.5. I had 10.7, and it’s necessary to “Software Update” this to the latest version. Other guides¹ may assist with filling in the gaps for more-recent versions of OS X.
Xcode Command Line Tools (Xcode CLT). At about 140MB, this gives us various essential build tools without needing the full Xcode package;
Homebrew. Mac package management has never been easier, or more reliable!
RVM. This is my preferred² Ruby version manager. It makes installing/updating Ruby easier, and gives you more options.
Ruby 1.9.3. It’s a well-established standard. I will make the switch to Ruby 2.x when it’s more mature and dominant.
Bundler. Managing gems is delightfully simple and transparent with this.
iTerm2. I haven’t yet found a Terminal program on any OS that I like more than iTerm2.
Sublime Text. Available for Mac, Windows, and Linux; it supports most of the stuff you can plug into TextMate, with many other cool features.
Git and GitHub. They’re just done so well, and really you can’t do without them.

Things NOT covered by this article:

Targeting specific platforms. I’m not yet worrying about building stuff specifically for OS X, iOS, Android, or otherwise. I’m sure there are plenty of excellent guides on the web if you’re looking to get heavily into conventional app development or otherwise use the full suite of tools provided by Xcode.
Database engine. I’d probably go for SQLite3 for basic stuff and private apps, and PostgreSQL for web apps or apps dealing with big data. I’m not much interested in MySQL anymore.
Shell. Though I’ve used Z-Shell (zsh) before and I like it, I will stick with the default bash for now.
Ruby on Rails.

NOTE: Developing on a Mac may not necessarily be the right choice for you. Be aware of some of the arguments for using other platforms before jumping head-long into purchasing a Mac or otherwise abandoning an existing platform that is working for you.

Checking existing environment

This is just a background check, for your reference. It might not really be that important, unless you already use your Mac for other development stuff and need to maintain an environment. You can skip to the next section if you prefer.

I started with a fresh (not-yet-updated) install of Mac OS X 10.7 (Lion) on an old Mid-2007 black MacBook (MacBook2,1, model A1181) with 2GB of RAM and an Intel Core 2 Duo CPU (x86 only³). I’ve found the performance of Lion and my dev tools, on this Mac, to be adequate.

This is how I inspected my existing environment, in Terminal:

Find out Mac OS X details:

$ system_profiler SPSoftwareDataType
Software:

    System Software Overview:

      System Version: Mac OS X 10.7 (11A511)
      Kernel Version: Darwin 11.0.0
      Boot Volume: Anton250GB
      Boot Mode: Normal
      Computer Name: OldMacBook
      User Name: Anton Maurovic (amaurovic)
      Secure Virtual Memory: Enabled
      64-bit Kernel and Extensions: No
      Time since boot: 1 day11:50

Check the versions of Ruby and Rubygems that come bundled with 10.7:

$ ruby --version
ruby 1.8.7 (2010-01-10 patchlevel 249) [universal-darwin11.0]
    
$ gem --version
1.3.6

Verify that there is not (yet) any C compiler, or make:

$ gcc --version
-bash: gcc: command not found

$ cc --version
-bash: cc: command not found

$ make --version
-bash: make: command not found

Installation Steps

NOTE: I only show use of sudo (i.e. root operations) where strictly required. Many commands are best run just as your regular, un-elevated user. Your user should still be in the class of “Administrators”, however, for when you get to steps that do require sudo.

These instructions are intended for OS X 10.7 and above. Earlier versions of OS X probably require that you download and install the full Xcode package from Apple, suitable for your specific version of OS X.

Pre-requisites

Use your Mac’s “Software Update” to ensure⁴ you have the latest version of your OS X.

Check system_profiler SPSoftwareDataType again:

$ system_profiler SPSoftwareDataType
Software:

    System Software Overview:

      System Version: Mac OS X 10.7.5 (11G63)
      Kernel Version: Darwin 11.4.2
      Boot Volume: Anton250GB
      Boot Mode: Normal
      Computer Name: OldMacBook
      User Name: Anton (amaurovic)
      Secure Virtual Memory: Enabled
      64-bit Kernel and Extensions: No
      Time since boot: 2:48

Check Ruby version:

$ ruby --version
ruby 1.8.7 (2012-02-08 patchlevel 358) [universal-darwin11.0]

Installing “Xcode Command Line Tools”

People have suggested osx-gcc-installer instead, but since SOME stuff can’t be compiled with it, even its maintainer (Kenneth Reitz) seems to advocate using Xcode Command Line Tools.

Xcode CLT is needed for Homebrew. So that we don’t have to install the full Xcode (over 1.6GB!) we’ll install “Xcode Command Line Tools” (between 100MB and 140MB):

Go to: https://developer.apple.com/downloads
You will need an Apple Developer account (which you can register for free).
Once you hit the main download page, you may need to search for “command line tools” to find the right one for your OS X version:
IF you have to do everything via command-line, for some reason, see the instructions for installing Xcode CLT via command-line. Otherwise, just do the following…
Double-click the DMG file you downloaded, to mount it.
From the Finder window that pops up, double-click Command Line Tools (...).mpkg or whatever your package is called.
Step through all defaults, to install.
Unmount the DMG.

Now we should have gcc, make, and a few other important things. For example:

$ gcc --version
i686-apple-darwin11-llvm-gcc-4.2 (GCC) 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2336.11.00)
...

$ make --version
GNU Make 3.81
...

$ git --version
git version 1.7.12.4 (Apple Git-37)

Installing Homebrew

Homebrew is described as “the missing package manager for OS X”. It is basically like the Debian/Ubuntu APT system, and makes it quite fast and easy to find software packages, install them, update them, and remove them. There is an alternative – MacPorts – but I strongly prefer Homebrew for its simplicity and reliability.

Go into Terminal and run:

ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

Check with:
```
brew doctor
```
In my case it has nothing to recommend: Your system is ready to brew. Otherwise, you may need to tweak some things to make it happy, but it should tell you what to do.
Run:
```
brew update
```

Installing Git, and configuring for GitHub

Now that we have Homebrew, installing packages is so much easier. We’ll start by installing Git, then configure it to enhance your shell prompt, test it out, and optionally link it up to your GitHub account, if you have one.

Run:
```
brew install git
```

Now, at this point I ran git --version and found it was still executing the old (Apple Git-37) version instead of the new one I just installed. I exited my Terminal and started up a new one, to load the latest config, and ran brew doctor again, which told me:

$ brew doctor
Warning: /usr/bin occurs before /usr/local/bin
This means that system-provided programs will be used instead of those
provided by Homebrew. The following tools exist at both paths:

    git
    git-cvsserver
    git-receive-pack
    git-shell
    git-upload-archive
    git-upload-pack

Consider setting your PATH so that /usr/local/bin
occurs before /usr/bin. Here is a one-liner:
    echo export PATH="/usr/local/bin:$PATH" >> ~/.bash_profile

…but there’s an error, in this one-liner at the end. Here is the exact, revised statement that I executed:

echo export PATH="/usr/local/bin:\$PATH" >> ~/.bash_profile

The difference is the extra backslash at \$PATH.

After executing that statement to update my ~/.bash_profile, I exited my Terminal, and then went into it again to ensure all settings were refreshed.
Now git --version gives:
```
$ git --version
git version 1.8.4
```
Configure Git, using your preferred personal details:
```
git config --global color.ui true
git config --global user.name "Yourfull Namehere"
git config --global user.email "ifyoureally@wantto.com"
    
git config --global push.default simple   # !! SEE BELOW !!
```
Note that the last option for push.default should only be set for Git 1.8.x or above. It tells Git that when we do a git push, we only want to push commits for the branch that we’re currently on rather than all branches. You don’t have to do this, if you don’t want.
You can now enhance your prompt, so that it will reveal information about your Git branch, any time you’re in a directory inside a Git repository. These instructions are adapted from this article, but have been re-written slightly to make it clearer what, exactly, you need to do:
1. First, download the .git-prompt.sh script to your home directory:
```
curl -Lo ~/.git-prompt.sh https://raw.github.com/git/git/master/contrib/completion/git-prompt.sh
```
2. Add the following lines to the end of your ~/.bash_profile script (creating the file if it doesn’t already exist):
```
source ~/.git-prompt.sh
    NONE="\[\033[0m\]"
     RED="\[\033[0;31m\]"
   GREEN="\[\033[0;32m\]"
  YELLOW="\[\033[0;33m\]"
    BLUE="\[\033[0;34m\]"
 MAGENTA="\[\033[0;35m\]"
   WHITE="\[\033[1;37m\]"
PS1="$GREEN\t$RED-$BLUE\u:$YELLOW\W$MAGENTA\$(__git_ps1)$WHITE\$$NONE "
# OR, if you don't want to use a colour prompt:
#PS1="\t-\u:\W\$(__git_ps1)\$ "
```
3. Reload your shell’s environment to see the new prompt:
```
source ~/.bash_profile
```
Create ~/projects:
```
mkdir -p ~/projects
```

Test git, and your updated prompt:

$ cd ~/projects
    
$ git clone https://github.com/mechanicles/ruby-tictactoe.git
Cloning into 'ruby-tictactoe'...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 6 (delta 0), reused 6 (delta 0)
Receiving objects: 100% (6/6), done.
    
$ cd ruby-tictactoe
21:57:52-amaurovic:ruby-tictactoe (master)$

NOTE appearance of the (master) branch identifier.

The following GitHub steps are optional, if you’re going to use GitHub…
Generate an SSH key, noting that a passphrase is optional.

Configure your git…

git config --global github.user "your_github_username"

Restart your shell; i.e. exit Terminal and then bring it up again.

Installing RVM

RVM – Ruby Version Manager – lets you easily install Ruby, and optionally multiple different versions of Ruby on the same machine, such as 1.9.3; 2.0.0; the retired 1.8.7; and even JRuby and Ruby Enterprise Edition. It can manage multiple Gemsets for each, and allow each project to specify particular Ruby and Gemset requirements at runtime.

Install RVM:
```
\curl -L https://get.rvm.io | bash -s stable
```
NOTE: The leading backslash is deliberate⁵.
Add the following as the last line of your ~/.bash_profile file:
```
[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm"
```
This ensures RVM will be loaded when you log in, and will hence activate when required.
Restart your shell (i.e. exit Terminal and then go back into it).

Check:

$ type rvm | head -1
rvm is a function
    
$ ruby --version
ruby 1.8.7 (2012-02-08 patchlevel 358) [universal-darwin11.0]

Install Ruby 1.9.3:
```
rvm install 1.9.3
rvm --default 1.9.3
```
Be aware: When testing these instructions on Mac OS X 10.8.5, I found that rvm install 1.9.3 failed about 22 minutes in, and an extra step was required. See below re tips for installing on Mac OS X 10.8 and above.

NOTE: This isn’t necessarily going to happen quickly, as it may have to do a lot of work in downloading prerequisites, and then compiling. For me, on my slow old MacBook, this took about 1 hour. On a 2013-model iMac with OS X 10.8.5, it took about 30 minutes.

Now run:

$ ruby --version
ruby 1.9.3p448 (2013-06-27 revision 41675) [x86_64-darwin11.4.2]
    
$ rvm list

rvm rubies

=* ruby-1.9.3-p448 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

Install Bundler

Bundler is a very popular, and widely-supported way to manage a set of Gems per each of your Ruby projects. By use of a Gemfile (which is a very simple Ruby script that dynamically defines dependencies for specific Gems and respective versions), you can ensure the correct environment is managed in the scope of your application for development, production, and other purposes. And it’s just so easy!

As per the instructions:
```
gem install bundler
```
Create the file ~/.gemrc:
```
---
:benchmark: false
gem: --no-ri --no-rdoc
:update_sources: true
:bulk_threshold: 1000
:verbose: true
:sources:
- http://rubygems.org
:backtrace: false
```
…this sets various global parameters for the gem command, in particular ensures the --no-ri --no-rdoc parameters are always used when installing gems. This is intended to speed things up, and makes the assumption that you will always use a documentation source other than the gem files themselves – e.g. online, such as from the excellent APIdock website.

Install optional stuff

The following packages are optional, but highly-recommended as they add a lot of value. You can also customise them as you need.

Install ImageMagick

If you intend to programmatically process images, say via a script or Ruby app, you will most likely find yourself using ImageMagick. In my case, I use it both via command-line (i.e. convert command) and via a Gem (with RMagick for Ruby).

I expected to get a stable ImageMagick install with a single Homebrew command: brew install imagemagick. However, after doing this, SVG files I wanted to process were randomly problematic. I found that the solution was to install ImageMagick specifically with librsvg integration. I did that as follows:

If ImageMagick has already been installed with Homebrew, remove it first:
```
brew uninstall imagemagick
```
librsvg needs to be installed before you can build ImageMagick against it. Note that this took over half an hour for me:
```
brew install librsvg
```
If you’re running Mac OS X 10.8 or above, this may give an error that X11 is absent, with a recommendation to install XQuartz. For more info, see below re tips for installing on Mac OS X 10.8 and above.
Then, install imagemagick specifically using the --with-librsvg option:
```
brew install imagemagick --with-librsvg
```

Install git-flow

git-flow is an extension to the git command that helps you manage formal development-grade and production-grade streams in any given repository. Sometimes this may be overkill for a small, internal, or otherwise private project, but it may still turn out to be more useful than you expect.

To understand git-flow better, I suggest you read the original description of the git-flow model, but bear in mind that it was written before the git-flow helper commands were created. That document just explains basically how it works.

Whether you read that or not, there is a great git-flow cheatsheet which shows clearly what the git-flow helper commands are, and how to use them.

So, to actually install git-flow, simply do this:

brew install git-flow

…and then verify it with:

$ git flow help
usage: git flow <subcommand>

Available subcommands are:
   init      Initialize a new git repo with support for the branching model.
   feature   Manage your feature branches.
   release   Manage your release branches.
   hotfix    Manage your hotfix branches.
   support   Manage your support branches.
   version   Shows version information.

Try 'git flow <subcommand> help' for details.

Fix `vim` config

I use vim for quickly editing files from time to time at the command-line, including over SSH. If you don’t use it, you can skip this section.

Grab a template that fixes cursor keys:

VIMRC_EXAMPLE="`ls -d1 /usr/share/vim/vim*/vimrc_example.vim | head -1`"
cp "$VIMRC_EXAMPLE" ~/.vimrc

Add the following to ~/.vimrc for other enhancements:

" Add these if needed:
"   filetype plugin indent on
"   syntax on
" Two-space soft tabs, always:
set tabstop=2
set softtabstop=2
set shiftwidth=2
set expandtab
" Line numbers:
set number
" Disable backup files:
set nobackup
" Configure F6 to toggle 'paste mode'
set pastetoggle=<F6>

The config file above does the following:

Uses a template that defines proper Vim handling of your Mac’s Home/End and other such navigation keys.
Globally uses ‘soft tabs’ (i.e. runs of space characters instead of actual tab characters), at intervals of 2 spaces.
Turns on line number display.
Disables generation of backup files that have a ~ appended. I find this really annoying, and since I use version control (Git) for most things it’s unnecessary. There are plenty of cases, however, where it might be better to comment out the set nobackup line so that you’re safe instead of sorry.
Configures the F6 key on your keyboard to toggle “paste mode”. In Vim you may find, by default, that it tries to apply some indentation ‘smarts’ to text that you type in, and when you try to paste in a block of text, things go awry. With the configuration shown above, you can press F6 while in Insert mode, and it will show that it has gone into -- INSERT (paste) -- mode. If you now paste in content while in this mode, its indentation will not be altered by Vim. Hit F6 again to exit out of paste mode.

There’s a vast amount of stuff you can configure and customise for Vim. For example, if you want, you can specify different tab formatting for different file types.

Install iTerm2

As a terminal replacement, there are many things I really like about iTerm2. Aside from being heavily customisable, it has features such as: saved profiles; session playback; split windows; and a lot of other conveniences that just make sense.

Go to: http://www.iterm2.com
Hit the ‘Download’ button (1.0.0 at the time of writing).
Extract the .zip file that you download, and you should end up with iTerm.app.
Move iTerm.app into your Mac’s Applications folder and, if desired, drag it to your dock.
Launch “iTerm”.

Install Sublime Text

Sublime Text is an excellent programmer’s text editor that is modelled on TextMate but with many other enhancements. It supports a lot of TextMate’s actual config files and syntax highlighting definitions, and is available for Mac, Windows, and Linux. I strongly recommend it because it is attractive, highly customisable, and rich in sensible features.

Go to the Sublime Text website, download it (v2.0.2 at the time of writing), open the .dmg, and drag the Sublime Text app into the Applications folder (as is typical of most simple Mac software installs).
Go into Applications and try launching it.
Quit out of Sublime Text.

Make sure you have a local ~/bin directory, and that $HOME/bin is part of your PATH. You can ensure that this is the case, using this:

cd ~
mkdir -p bin
if [[ "$PATH" == *"$HOME/bin"* ]]; then
    echo -e "\n--- $HOME/bin is already in your path\n"
else
    echo 'PATH=$PATH:$HOME/bin' >> .bash_profile
    source .bash_profile
    echo -e "\n+++ \$HOME/bin has been added to your path in .bash_profile\n"
fi

NOTE that while this will update your PATH in the current shell, any other open shells will not yet be up-to-date unless you run:

source ~/.bash_profile

Install the subl command-line utility:
```
ln -s "/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl" ~/bin/subl
```
This allows you to launch Sublime Text from command-line, to get it to open a file or folder. See the subl command-line utility documentation for more info.
Try out subl; if we assume you have the ruby-tictactoe repo as per the example given earlier in this article, you should now be able to:
- Open an individual file:
```
subl ~/projects/ruby-tictactoe/README.md
```
- Open the whole “project”:
```
subl ~/projects/ruby-tictactoe
```
Now, if you want, you can customise Sublime Text. For example, I write a lot of documents in kramdown, and there are two ‘Themes’ (i.e. colour schemes) which seem to show Markdown/kramdown highlighting the best:
- Dawn: Light background.
- Sunburst: Dark background – which I prefer because it’s easy on the eyes but also gives great highlighting in general.
To choose a colour scheme, go to the main “Sublime Text 2” menu => “Preferences” => “Color Scheme” and pick one.

NOTE: If you use kramdown files with the .kd file extension, you will either need to specify that each file you open is in Markdown format (by clicking the bottom-right corner of the window and choosing ‘Markdown’ => ‘Markdown’ or the same via the ‘View’ => ‘Syntax’ menu), or configure Sublime Text to recognise .kd automatically as Markdown. Below are some links with more information on how to customise Sublime Text, including for Markdown/kramdown:

Extended Markdown support for Sublime Text.
Adding Markdown/kramdown syntax highlighting to any Sublime Text theme: Make sure you read all the instructions for where to insert the given code.
Example of extending Markdown syntax highlighting with extra kramdown features.

Other stuff worth checking out

The following is just a collection of other random pointers which you might find to be of interest in your development workflow:

If you’re going to be developing web apps, you will almost certainly be using Ruby on Rails (right?) but you might also want to give Sinatra a try if you’re looking to build lightweight apps and utilities that need a simple web interface.
For spinning up and testing web apps, especially where you want to simulate multiple domains and sub-domains, you might also want to check out Pow and Powder.
In terms of a good database platform both for local development, testing systems, and even enterprise production systems, I’ve grown quite fond of PostgreSQL. A project I haven’t checked out yet, but which sounds promising, is Postgres.app.
If you work with GitHub a bit, and in particular if you participate with a few Open Source projects, you might want to check out hub.

Troubleshooting

If you started from a clean machine and exactly followed the instructions above, I would expect that everything worked perfectly. It is possible, however, that things will go wrong (even if you did start with a clean machine), due to various factors:

You’re using a more recent version of OS X, for which you should be able to find solutions (e.g. see below) – resorting to Googling actual error messages if necessary.
You may have other stuff pre-installed which is getting in the way, particularly packages managed by something else such as MacPorts or Fink. If that’s the case, you may need to migrate from MacPorts to Homebrew, or whatever.
You may have chosen to customise your installation paths or other such things in a way which challenges the assumptions that these various tools make. In this case, there should be a way to diagnose these problems or get help, again by Googling or asking questions via one of the Stack Exchange sites such as Super User, Stack Overflow, or Ask Different. You can also try Homebrew’s self-diagnosis (i.e. brew doctor), and RVM troubleshooting tips.
Since I wrote this article, some of the tools and packages I documented may have been deprecated, either rendering them unavailable, or making the current default a newer version that has different compatibility. If that’s the case, you might have to investigate other people’s guides to fill in the blanks for getting new versions to work.

If you encounter any problems, please provide feedback by commenting below or by filling in my contact form. Feel free to ask any questions and report things you’re stuck on, though I would be hugely grateful if you identify a solution to any issues you find, and want me to include them in this article.

Tips for installing on Mac OS X 10.8 and above

While the instructions above worked fine for me on Mac OS X 10.7.5, I hit a couple of errors while installing on Mac OS X 10.8.5. This is how I worked around them:

While trying to install a Ruby version for the first time using RVM (i.e. with rvm install 1.9.3), I hit an error that gave output along the lines of:

 Installing Ruby from source to: /Users/anton/.rvm/rubies/ruby-1.9.3-p484,
 this may take a while depending on your cpu(s)...
...etc...
 ruby-1.9.3-p484 - #applying patch /Users/anton/.rvm/patches/ruby/GH-488.patch.
 ruby-1.9.3-p484 - #configuring.
 Error running './configure --prefix=/Users/anton/.rvm/rubies/ruby-1.9.3-p484
  --with-opt-dir=/usr/local/opt/libyaml:/usr/local/opt/readline:/usr/local/opt/libksba:/usr/local/opt/openssl
  --without-tcl --without-tk --enable-shared',
 showing last 15 lines of /Users/anton/.rvm/log/1390447207_ruby-1.9.3-p484/configure.log
...etc...
checking target system type... i386-apple-darwin12.5.0
 checking whether the C compiler works... no
 configure: error: in `/Users/anton/.rvm/src/ruby-1.9.3-p484':
 configure: error: C compiler cannot create executables
 See `config.log' for more details
 There has been an error while running configure. Halting the installation.

A further inspection of /Users/anton/.rvm/src/ruby-1.9.3-p484/config.log revealed:

...
 configure:3417: /bin/gcc-4.6 --version >&5
 ./configure: line 3419: /bin/gcc-4.6: No such file or directory
...etc...

For whatever reason, the build process assumes that /bin/gcc-4.6 exists, but in our case it is actually elsewhere (though still in the PATH): /usr/local/bin/gcc-4.6

The proposed solution for this is to simply symlink gcc-4.6 where the script expects it:

sudo ln -s /usr/local/bin/gcc-4.6 /bin/gcc-4.6

After this, you should be able to resume installing a Ruby version with RVM.

X11 has been removed from Mac OS as of OS X 10.8. Since librsvg (which we require for ImageMagick) relies on X11, you may get an error when trying to install it with Homebrew on OS X 10.8 and above. The Apple-recommended solution is to install XQuartz.

Once XQuartz is installed, you may be advised that you have to log out and log back in again. After doing this, you should be able to resume installing ImageMagick with librsvg.

Installing Xcode CLT via command-line

I just provided these instructions as an example of how some of the installation steps given above can be done remotely via SSH instead of via the Mac OS X GUI. In particular, this shows how you can mount a .dmg file, and use installer to install from a .pkg (or .mpkg) file.

Download Xcode Command Line Tools however you can, and get the file up to the filesystem of the Mac onto which you will install. If we assume for now it’s in ~/Downloads, and called something like xcode462_cltools_10_76938260a.dmg…

Go into Terminal and mount the DMG:

cd ~/Downloads
hdiutil attach xcode*cltools*.dmg

Install the extracted .mpkg:

cd /Volumes/*"Command Line Tools"*
time sudo installer -verbose -pkg *.pkg -target /

Test:
```
gcc --version
```

Unmount the DMG:

hdiutil detach /Volumes/*"Command Line Tools"*

Conclusion

You should now have quite a capable Ruby development environment, that is easy to manage and reconfigure. While not a complete development environment for other platforms, this combination of tools should make for a stable and sensible foundation to install other software to suit your programming and testing needs, including:

Other Ruby favourites, e.g. rspec, Cucumber, and Capistrano (or maybe Mina or Chef?)
Other compilers and interpreters⁶.
Other shared libraries and utility packages.
Tools such as GIMP, Jenkins, and VirtualBox (maybe with Vagrant?)
Sublime Text plug-ins, packages, and other customisations. See also: Package Control.
The full Xcode platform.

In coming articles, I may switch between different environments (including Mac, Windows, and Linux). There are some cases where I will build upon what I’ve written in this article, showing installation guides that assume you’ve already taken these steps or the ones in my Cygwin article, if you’re using Windows.

For now though, good luck, and happy coding!

For information which may help with getting a similar environment working on OS X 10.8 (Mountain Lion) or above, see: The Hitchhiker’s Guide to Riding a Mountain Lion ↩
Another alternative to RVM is rbenv. With ruby-build installed, RVM and rbenv both offer very similar functionality, and in some respects rbenv may be the smarter, more-lightweight choice if you’re using Bundler. Here is a brief guide that shows use of rbenv on a Mac.↩
That is, only 32-bit capable, not x64-compatible. Most Macs since then have a 64-bit capable CPU.↩
Many tools will require that your OS X is up-to-date. At the time of writing, OS X Lion (10.7) is up to 10.7.5. The Apple “Command Line Tools (OS X Lion) for Xcode - April 2013”, for instance, needs 10.7.4 or above.↩
A shell command prefixed with a backslash will ignore any alias of that command, if there is one in effect. For more information, see this question on Stack Overflow ↩
You may find several other compilers and interpreters are already installed and ready for use, including perl, python, php, and gcc. Some of these, however, can be replaced with newer versions that are nicely managed by Homebrew. In any case, though, I recommend reading more about them before trying to install or replace these defaults.↩

Wrangling Ruby and ImageMagick in Cygwin

2013-09-11T00:00:00Z

Cygwin can be a clever way for Windows environments to leverage the power of tools that might otherwise only be available in the Unix realm. If you attempt Ruby and ImageMagick stuff in it, though, be prepared for a fight…

Introduction
The Problem
My Specific Problem with Ruby and ImageMagick
My Solution
The Steps
Troubleshooting

Introduction

Rejected titles for this article include: (a) “It’s not whether you Cygwin or Cyglose: Just quit now!”; (b) “Build a Ruby Goldberg Machine in 146 Easy Steps”; and (c) “Cygwin and Ruby: Forking Hell!”

I won’t explain much of Cygwin other than to say it’s a way to run Unix software natively on Windows. More-precisely, it’s a platform that allows for Unix software to be compiled to target Windows. This is done with shared Cygwin DLLs which seek to provide POSIX-compliant system calls, path mapping, and so-on through a Unix compatibility layer.

While Cygwin is a clever piece of work and a means to an end, I’ve concluded that it is not a suitable way to build a complete development environment, especially where Ruby is involved. You will probably be better off if you switch entirely to (say) Linux, or stick with Windows, optionally with Cygwin playing a minor role in your toolchain.

Having said that, I will share my experiences with getting Ruby, RVM, ImageMagick, and ultimately my entire nanoc site build process to work under Cygwin.

The Problem

If you don’t care about the background of the issues, and just want to trace my steps that arrive at a usable environment, just see My Solution and The Steps below.

One great thing about Unix software is the intent that the source code be portable between different Unix flavours. Libraries and conventions are used, as defined by the POSIX standards, such that there are accepted ways that common tasks are usually done. Most free and open Unix software is initially distributed as source code, able to be compiled specifically for the target system. In principle, any Operating System that is at least mostly POSIX-compliant should be able to compile and run this software without issues.

Unfortunately, Windows is not particularly POSIX-compliant, and while Cygwin makes a noble attempt to bridge the gap, there are some things which either haven’t been adequately realised in Cygwin, or will never be possible due to key differences in Windows’ core design.

One issue which comes up regularly is fork() problems, related to multi-threading. While Unix software relies heavily on the fork-exec model, Windows uses a completely different approach which is not compatible. Cygwin attempts to work around this by ensuring libraries (e.g. DLLs) will be loaded into fixed, known address spaces between processes, and this requires “rebasing” of the libraries to prevent collisions (and hence prevent them from relocating).

In dealing with this issue, the rebaseall command comes up a lot, and there are discussions on the topic and why the issue manifests, but it can’t always be solved because:

The rebaseall command doesn’t always know how to automatically find all libraries/modules that may need treatment in order to be loaded properly;
Sometimes there simply isn’t enough address space for all libraries; and
Adding a new Cygwin package may require that you rebase all over again.

My Specific Problem with Ruby and ImageMagick

I’ve found that the fork() problem has the potential to be significantly harder to deal with when you’re using Ruby, as each gem may require its own library to be loaded by the Ruby environment, and it is hard to get the rebaseall command to consider these.

When I started using the RMagick gem, I hit a wall and I couldn’t proceed. RMagick provides Ruby bindings for the ImageMagick image processing libraries. I had intended to use it to process the images of my blog, producing inline-sized versions and thumbnails from full-sized originals, while also handling things like web optimisation. Instead, though, I was met with errors along the lines of the following, at the instant that Ruby tries to load the RMagick gem via require 'rmagick':

4 [main] ruby 3004 child_info_fork::abort: C:\cygwin\bin\cygpixman-1-0.dll: Loaded to different address: parent(0x5DF00000) != child(0x2B80000)
2 [main] ruby 284 child_info_fork::abort: C:\cygwin\bin\cygpixman-1-0.dll: Loaded to different address: parent(0x5DF00000) != child(0x5B0000)
1 [main] ruby 4548 child_info_fork::abort: C:\cygwin\bin\cygpixman-1-0.dll: Loaded to different address: parent(0x5DF00000) != child(0x370000)
2 [main] ruby 3052 child_info_fork::abort: C:\cygwin\bin\cygpixman-1-0.dll: Loaded to different address: parent(0x5DF00000) != child(0x2B50000)
...

Supposedly, this problem should all but disappear in a 64-bit version of Cygwin, but I had problems with that too. Namely, curl is faulty, and this is critical to some of the other installation processes on which I rely. So, I had to stick with the 32-bit version of Cygwin and figure out how to continue without RMagick.

My Solution

Though the rebase issue is more general than just Ruby and ImageMagick, it was only since I started loading RMagick in my project that I started having fork() problems. So, I had considered replacing RMagick with the (more lean) FreeImage Ruby bindings (i.e. the free-image gem), and even got it working in a way that I liked… But I then learned that it has no support for vector images (e.g. SVG files), and I rely on this for many diagrams in my site. So, what to do?

I decided to rework the RMagick code I had and instead call the convert command-line utility provided with a standard installation of ImageMagick. This is a bit of a kludge, but I simply couldn’t find a way to get RMagick to work properly in my app under Cygwin. I left the RMagick code in place for other platforms, but routed around it to instead call system("convert ...") when using Cygwin.

By way of an example, the following RMagick code:

# Load the image:
pic = Magick::Image.read("my_file.png").first
# Resize down (hence trailing ">" after dimensions) to fit a 400x300 space:
pic.change_geometry("400x300>") do |cols, rows, img|
  img.resize!(cols, rows, Magick::CatromFilter)
end
# Reduce to 64 colours without dithering:
pic = pic.quantize(64, Magick::YUVColorspace, Magick::NoDitherMethod)
# Write out an 8-bit PNG image:
pic.write("png8:output_file.png")

…became something like this:

# Build one long command-line string...
# Load the file:
cmd =  "convert my_file.png "
# Resize (scale down, only; not up-size) to fit within a 400x300 space:
cmd << "-resize '400x300>' "
# Reduce to 64 colours (web optimisation):
cmd << "-quantize yuv +dither -colors 64 "
# Write out the file as an 8-bit PNG:
cmd << "png8:output_file.png"
# Now call the command...
convert_ok = system(cmd)
raise "ERROR: convert command failed with status: $?" unless convert_ok

The Steps

This documents what I did to install Cygwin from scratch, with some additions, followed by RVM, Ruby, and ImageMagick.

Part 1: Install Cygwin

I had to install the 32-bit version of Cygwin because it looks like there is a bug with the 64-bit version of curl on Cygwin. This leads to problems including:

Cannot install RVM easily.
apt-cyg is broken.

So, this is the procedure I followed, influenced by instructions for Installing RVM on Cygwin:

Download the Cygwin Installer, specifically the 32-bit version: setup-x86.exe.
Make sure you are an Administrator when you run the installer, and if you’re using Windows Vista, 7, or above, be sure to right-click the installer and select the “Run as Administrator” option.
Advance through the wizard to the “Local Package Directory” and specify C:\cygwin_setup.
Advance through to the mirror list and choose any mirror which sounds close to you. In principle, any mirror should do, though occasionally some of them are not completely up-to-date.

In the package list, add the following besides the defaults:

ca-certificates
colorgcc      (if available)
curl
gcc           (note that this is "Src?" only)
gcc-core      (this is the compiler)
git
git-completion
git-gui
gitk
git-svn
ImageMagick
libMagick-devel
libncurses-devel
libtool
libxml2-devel
libxslt
libxslt-devel
libyaml0_2
libyaml-devel
make
mercurial     (if available)
ncurses
openssh
openssl
openssl-devel
patch
pkg-config
readline
rsync
subversion
unzip
vim
wget
zlib
zlib-devel

Proceed with the installation and it starts downloading what it needs.
At the end, launch the “Cygwin Terminal” as Administrator and verify it seems to work OK, optionally setting the scrollback count to 20,000 lines or more.

Part 2: Install `devtools` and RVM

The devtools repository is an unofficial set of scripts to assist with setting up an RVM environment, including a script for Cygwin. These instructions are taken from: Installing RVM on Cygwin.

Run the following commands (noting that the actual paths are important, in this case):

mkdir -p repositories/developwithpassion
cd repositories/developwithpassion
git clone git://github.com/developwithpassion/devtools
cd devtools
./osx_or_cygwin_kick_off

This will have created a file such as $USER.settings (i.e. your_windows_user.settings) which you can alter to:
1. Specify your GitHub account details (if you have one).
2. Comment out all of the :windows[:paths] options, since they probably are not relevant for your machine (as they were indeed not relevant for mine).
Run this command again:
```
./osx_or_cygwin_kick_off
```
…which will now use your ...settings file to do its install.
You may see some errors along the way, but just ignore them until you see a prompt to press any key to continue; hit ENTER each time it prompts you.
As it progresses, it will compile a version of Ruby (1.9.3?) and this will take a while; probably more than 15 minutes. Afterwards it will wait for you to hit ENTER again before trying to install Ruby 2.0.0.

NOTE: It may stall while installing Ruby 2.0.0, after this point:

Installing rubygems-2.0.6 for ruby-2.0.0-p247.........(and so on)......
Installation of rubygems completed successfully.
Saving wrappers to '/home/anton/.rvm/wrappers/ruby-2.0.0-p247'...........

ruby-2.0.0-p247 - #adjusting #shebangs for (gem irb erb ri rdoc testrb rake).
ruby-2.0.0-p247 - #importing default gemsets, this may take time.................

After waiting at least half an hour, I hit CTRL+C. It gave some errors, but I was able to proceed as follows…

Exit the Cygwin Terminal and launch it again. This will ensure the correct environment gets loaded.
At this point, you will probably be on Ruby 2.0.0. Install the latest Ruby 1.9.3 and switch to it:
```
rvm install 1.9.3
rvm use 1.9.3 --default
```

Part 3: Install `apt-cyg`

apt-cyg is loosely equivalent to APT (e.g. apt-get). It is a way to search for, and install packages from the Cygwin command-line. It is not perfect but can be a convenient way to install packages on demand or via a script. I recommend installing it, as it may come in handy.

Run the following commands, which dump apt-cyg directly into your path and then make it executable:
```
svn --force export http://apt-cyg.googlecode.com/svn/trunk/ /bin/
chmod +x /bin/apt-cyg
```
Use apt-cyg to install something:
```
apt-cyg install bc
```
Verify that it worked:
```
bc --version
```

NOTE: If you retrospectively install any packages with apt-cyg (or the Cygwin setup-x86.exe for that matter), you may need to take the following steps, if you start getting errors related to fork():

Exit out of any Cygwin processes, including the Cygwin Terminal.
Launch a Windows Command Prompt, “As Administrator”.

Run:

c:\cygwin\bin\dash -c '/usr/bin/rebaseall'

Part 4: Enable OpenSSH server

This assumes you want to be able to SSH into your machine and use the Cygwin command-line (i.e. your default shell in Cygwin). Being able to do so is quite convenient, but not required in this process, and may pose security risks depending on your circumstances.

The steps below are based on these instructions:

Run:
```
ssh-host-config -y
```
…and when prompted, supply any password for the cyg_server user that it will create.
Log in as each user that will need SSH access (or just stay as the current user), and per each run:
```
ssh-user-config -y
```
…hitting ENTER to avoid entering a passphrase for each key.
Start the sshd service with:
```
cygrunsrv -S sshd
```
You should now be able to SSH into your host, with your Windows username and password.

NOTE: Doing this will probably reveal a new “Privileged server” user on your Windows login screen. For more info, see: here.

Part 5: Fix `vim` config

vim is my preferred editor. If you don’t use it, you can skip this section.

Grab a template that fixes cursor keys:

cp /usr/share/vim/vim73/vimrc_example.vim ~/.vimrc

Add the following to it for other enhancements:

" Add these if needed:
"   filetype plugin indent on
"   syntax on
" Two-space soft tabs, always:
set tabstop=2
set softtabstop=2
set shiftwidth=2
set expandtab
" Line numbers:
set number
" Disable backup files:
set nobackup

Part 6: Set yourself up for GitHub

Again, these steps are only required if you plan to use git (and GitHub).

Create a place where project repos can be kept. For example:

cd ~
mkdir /cygdrive/c/projects
ln -s /cygdrive/c
ln -s c/projects

Configure Git:

git config --global color.ui true
git config --global user.name "Your Full Name"
git config --global user.email "your.email@address.com"

Set up GitHub SSH keys.

Part 7: Create an example Ruby project

Create a directory for your project:
```
cd ~/projects
mkdir mydemo
cd mydemo
```
Create files that tell RVM which Ruby version to use, and that you want a specific set of gems to be tracked for this project:
```
echo "1.9.3" > .ruby-version
echo "mydemo-gemset" > .ruby-gemset
```
Change out of, and back into the directory, to get it to reload the RVM config:
```
pushd ~
popd
rvm list gemsets
```
…the final line of which should show something like:
```
=> ruby-1.9.3-p448@mydemo-gemset [ i386 ]
```
Install Bundler:
```
gem install bundler
```
Create a Gemfile which is used by Bundler, for now just to select v1.1.1 of the adsf gem:
```
source 'https://rubygems.org'

gem 'adsf', '1.1.1'
```
Test Bundler, getting it to read and respect Gemfile:
```
bundle install
```

Test that it worked:

which adsf
# /home/myuser/.rvm/gems/ruby-1.9.3-p448@mydemo-gemset/bin/adsf

Troubleshooting

If you get child_info_fork errors, try:

Run this command, to find any modules (i.e. that may have been installed by Ruby gems):
```
find ~ -iname '*.so' > /tmp/rubygems.so.list
```
Exit any Cygwin Terminals or processes.

Go in to an Administrator command prompt and run:

c:\cygwin\bin\dash -c '/usr/bin/rebaseall -T /tmp/rubygems.so.list'

More Packaging Designs for Seeed Studio

2012-06-26T00:00:00Z

I’m not a qualified or professional graphic designer, but from time to time I get the opportunity to contribute to a company’s marketing material. Seeed Studio have commissioned a few designs in the past, which I’d like to share here.

Seeed Studio is a company based in Shenzhen, China. They are part of a new breed of businesses that cater to the Open Hardware community and “maker” movement. Their products target the interests (and the tight budgets) of the growing market of electronics hobbyists, hardware design enthusiasts, and inventors.

One thing that gives Seeed an edge and really engages their customers, is close involvement with the community they supply: both sourcing and sharing designs within that community. In that spirit, individuals around the world often contribute to various aspects of Seeed’s production.

I was pleased to get involved, by contributing some graphic design work. This began with a winning box-art design I submitted to one of their competitions, and continued with a few other commissioned works…

Maker Faire Banners

Seeed Studio exhibited at the Bay Area Maker Faire in 2011 and asked me to come up with some banner designs that illustrated their open approach to development, prototyping, manufacturing, and marketing:

Wall banners for Seeed's booth at Maker Faire

I designed the banners to work together, or separately, and demonstrate the flow of ideas from inception to production. See also: Seeed’s original blog post.

ADK Dash Kit - Box Art

Seeed distribute their own version of the Android Open Accessory Development Kit, known as the Seeeduino ADK. They decided to pair it up with some of their Grove real-world interface accessories, to create the ADK Dash Kit. Using a new universal box template, they needed a design for a sticker that would wrap around the box, and communicate the great sensory, control, and feedback capabilities of the kit.

ADK Dask Kit wrap-around sticker design

The design brief specified use of the existing Seeed corporate image, while adding some geek appeal and tying it in with Google Android. I created a few icons and other visual metaphors that reflect the components supplied in the box.

Product shots of the ADK Dash Kit

Rainbow Cube, Ready to Shine - Box Art

One of the more aesthetic kits produced by Seeed is the “Rainbow Cube”, which is a 4x4x4 array of RGB LEDs. The “Rainbow Cube, Ready to Shine” combines a pre-assembled Rainbow Cube, in an acrylic case, with everything required to start programming it straight away – including an Arduino-compatible microcontroller/driver board.

Seeed commissioned me to design the packaging for this product, which required an eye-catching main box and a smaller accessories box that would be included inside. This is a 3D render of the main box:

Test render of the 'Rainbow Cube - Ready to Shine!' box artwork

After some minor changes, here is how the final product turned out, including the smaller accessories box:

Rainbow Cube, Ready to Shine! The final product

One challenge with this design was the stylised sketch of the device itself. Instead of drawing it, it was easier to model the whole thing in 3D and convert it to vector art.

Anton's Warm Chicken Salad

2012-03-17T00:00:00Z

One day I needed to whip something up quickly, using only what I had in my fridge and pantry. Fortunately, it turns out I actually had a lot of good stuff. So, it wasn’t too hard to put together a light, delicious recipe…

Anton's Warm Chicken Salad, being heartily enjoyed

I expect that any sort of “Warm Chicken Salad” is something in which you can easily exchange various ingredients to suit your taste. This recipe includes some key ingredients that I like, to make a basic “sauce” that you could probably put over any sort of salad, rice, or pasta.

Note that I really enjoy balsamic vinegar. You may prefer to cook with a little light wine instead, and use a dash of a simple salad dressing over the dish (if any at all).

Ingredients

1 x Large Onion, chopped
2 x Rashers Middle Bacon, chopped
12 x Cherry tomatoes, quartered
1 x Cos lettuce, cut into fat ribbons
¾ of a red capsicum, cut into fine strips
6 x Large button mushrooms, finely diced
170g Semi-dried tomatoes in their own oil
2 blocks, Danish fetta, cubed
2 x Chicken breasts, diced
1 tsp Chicken stock
1 tsp Paprika
½ tsp Chilli flakes
3 tbsp pizza sauce
2 slices of a good, thick white bread – toasted, buttered, then dried in the oven (75°C) until crunchy and cut into croutons
Olive oil
Balsamic vinegar
Shaved parmesan cheese

Method

Brown onion in 1bsp oil, then the bacon.
Lower the heat & add capsicum, chicken stock, paprika, chilli flakes, and half the mushroom.
Simmer until capsicum is soft, then sear, then put this mix aside.
Remove any burnt muck from the pan, add more oil, and lightly cook semi-dried tomatoes (with their oil) and half the fetta on medium heat. Add chicken, and a few bursts of balsamic to the uncooked side of the chicken.
Cook for a while, stirring occasionally, until it starts to thicken. Start adding a little more balsamic when the chicken is mostly cooked.
Add pizza sauce and the earlier capsicum mix, cook a short while longer until all well-mixed.
Turn off heat, add croutons, stir up.
Combine and toss lettuce, cherry tomatoes, and remaining raw mushroom and fetta. Dress with more balsamic, and a touch of oil, salt, and pepper to taste.
Top the salad with the cooked mixture, and parmesan cheese.

Electronics, part 1: Analog Basics

2012-02-19T00:00:00Z

Despite playing with electronics for years, there’s a lot I didn’t know about the basics. I find that a good way to learn something and understand it well, is by explaining it to someone else. This article is the first of (hopefully) many, and kicks off with some simple concepts that are fundamental to all electrical systems.

Introduction
Assumptions
What does “Analog Electronics” mean?
What is an electrical circuit?
Understanding Current, Voltage, and Resistance
Bringing it all together with Ohm’s law
Examples
Conclusion
Further Reading

Introduction

In these articles I hope not only to teach others, but reinforce my own understanding. If you think I’ve explained something incorrectly or poorly, please correct me. If I pass briefly over a topic that you feel really needs more detail, suggest a web link or a short addition that I can include here.

In studying electronics, you’ll learn about two models: “Analog Electronics” and then “Digital Electronics”. Both are valid, and have their own specific applications. This article gives a brief summary of analog electronics, and simple facts which are crucial to all electrical behaviour.

With an understanding of analog electronics, you will be able to examine and even design more complex systems, including the analog components and behaviours that affect, support, and drive digital systems.

I will avoid the physics of electronics, and some of the detailed theory. I am going to focus more on the practical side, so I can take you through these topics quickly. If you want the “nitty-gritty”, maybe take a look at the Further Reading section.

Assumptions

Even if the following concepts are all new to you, hopefully you will still be able to follow this article.

In these articles, I will assume that:

You observe Electrical Safety – do not experiment with anything connected to mains power.
You’ve had at least some basic hands-on experience with electricity, maybe just to light something up, install or fix some wiring, or charge a car battery – even if just from someone else’s instructions.
You more-or-less know what “conductors” and “insulators” are;
You know how to interpret at least the basics of circuit diagrams (i.e. schematics);
Optionally, you know the difference between conventional current and electron flow.

What does “Analog Electronics” mean?

Commonly, “analog electronics” refers to designs that respect electricity as a continuous, variable quantity, where even small variations in electrical levels may be important, calculated, and used purposefully. These variations have a direct measurable effect on (and drive operation of) the system as a whole.

Figure 1: Example of an analog system

The word “analog” means “proportional”. This describes how “information” in the system is directly represented by varying electrical levels. For example, a microphone senses air pressure waves (sound), and may express the pressure as a tiny, proportional, electrical level. That electrical level can then be modified by an electronic device, to proportionally enlarge (amplify) it. The now-amplified signal may then be converted back into sound, by mechanically driving a loudspeaker.

All electrical systems are fundamentally analog in nature: The analog model describes electrical phenomena in continuous mathematical terms, and we’ll start with the simplest aspects of this.

What is an electrical circuit?

The following is an example of the simplest circuit, but don’t try assembling it as described because it has no limiting factors, and hence will have damaging effects.

Any work done by an electrical device, is because of “charge” flowing through it. “Charge” is like a quantity of electricity¹, and is often visualised as a liquid. It can be made to “flow” in one direction or another through the material of a “conductor”, such as a metal. The solid of the conductor “contains” the charge in much the same way that the hollow inside a pipe can contain water.

Figure 2: Simplest complete circuit

If an electrical conductor is in direct physical contact with an electrical energy (“voltage”) source, electrical charge will flow at a given rate (“current”) so long as it has a return path. The amount of current is restricted by the imperfect nature of the conductor (“resistance”), which is usually deliberately controlled. This is a circuit, in that an energised charge can come from one place, follow a direct path, and return to another place – to be re-energised for as long as the energy supply lasts.

Example conductor: A continuous piece of metal, such as a wire.
Example voltage source: A battery, with two terminals. High-energy charge leaves via one terminal – call it “positive” (usually indicated by a plus ( $+$ ) symbol or a red marking).
With a battery, the return path is via the other terminal that receives charge that has spent its energy – call it “negative” (usually indicated by a minus ( $-$ ) symbol, or a black marking).

Note that the source of energy (the positive end, which has the “higher relative voltage”) is sometimes said to “source current”, while the return path (the negative end, which has the “lower relative voltage”) is said to “sink current”.

Figure 3: Simple lightbulb circuit

Now, if a gap is created in the circuit (i.e. a cut and separation in the conductor)…

And a suitably-chosen component (e.g. lightbulb) is inserted…
Such that electrical charge is able to flow into one end of it…
And flow out of the other end and back onto the return path…

…then a simple useful circuit has been created, as the current supplies energy that lights the bulb. It is the insertion of extra components and more paths between the voltage source’s positive and negative terminals that allows for creation of more complex circuits that perform useful tasks.

Figure 4: A broken, or 'open' circuit

Why is the circuit configuration (i.e. return path) necessary? A voltage source (battery) does not simply “leak” or eject charge as soon as a conductor is attached. Rather, energy is added to the charge as it passes through the voltage source. If there is no charge arriving at the negative end, then there is nothing to energise and push onwards. Hence, no current will flow.

In this sense, a voltage source is like a pump. You will notice in Figure 4 that the bulb is not lit because there is no current: Though a conductor path apparently joins a positive terminal with a negative one, there is no way to continuously get charge into (or out of) the batteries, and hence they have no effect.

WARNING: When mains power is involved, touching even one terminal may harm or kill you. The voltage is high enough that a lethal current can pass through your body and complete a circuit with the ground beneath you, even if it doesn’t appear that there’s a conductor path between you and the ground.

Understanding Current, Voltage, and Resistance

I’m not going to explain the details of what current, voltage, and resistance actually are at the physical level, but here’s a summary of how they’re the most fundamental characteristics of an electrical circuit:

Current

Denoted $\mathbf{I}$ , “current” is an instantaneous measurement of the rate of flow of electric charge. It is because of current that there is activity in a circuit. It can be imagined that as current increases, a circuit becomes more “active” or more “energised”. Current is measured in “Amperes” (or “amps”, more commonly) – denoted A.

Resistance

Denoted $\mathbf{R}$ , “resistance” is the property of an electrical component (or simple conductor) to restrict the flow of charge (i.e. to resist, and hence reduce, the current). It’s measured in “Ohms”, denoted Ω. With higher resistance, there will be less current.

Voltage

Denoted $\mathbf{V}$ , or sometimes $\mathbf{E}$ , “voltage” can be thought of as relative electrical “pressure” that encourages charge to flow (and hence “causes” current). More-formally it is a difference of electrical potential energy, between two points, that acts as a force to cause electrons to flow through a suitable conductor medium. Voltage is measured in “volts”, denoted V.

Bringing it all together with Ohm’s law

Ohm's Law Triangle

So, voltage causes current, but current is restricted by resistance. Ohm’s law explicitly states the inter-dependence between voltage ( $\mathbf{V}$ ), current ( $\mathbf{I}$ ), and resistance ( $\mathbf{R}$ ):

$\mathbf{V} = \mathbf{IR} \quad \therefore \quad \mathbf{I} = \frac{\mathbf{V}}{\mathbf{R}} \quad \therefore \quad \mathbf{R} = \frac{\mathbf{V}}{\mathbf{I}}$

When you have:

Any pair of points in a circuit…
That have a voltage difference between them (i.e. a difference in potential)…
And are connected by an uninterrupted electrical path…
For which, you can express a total equivalent resistance…
With no other external voltage influences along that path…

…then there will be a current that is equal at all non-divided points along that path, and which can be calculated using Ohm’s law.

Examples

Very simple applications of Ohm’s law are demonstrated in the circuit diagrams below. Though these specifically use a known voltage and resistance to calculate current, you can use the identities of Ohm’s law with any two known variables to calculate the third unknown variable.

Though it appears most of these examples are not circuits, the presence of a voltage difference at points A and B implies that they’re connected to an unseen voltage source that completes the circuit. You can assume that the voltage source is a battery, power supply, or possibly even two points in a larger circuit.

Figure 5: Example circuits demonstrating Ohm's Law

Example 1

The total resistance between points A and B is shown to be 350Ω, while the voltage difference is 7V. So, the current from A to B (and at all points along the undivided path) is:
$\mathbf{I} = \frac{\mathbf{V}}{\mathbf{R}} = \frac{7}{350} = 0.02$
Hence, $\mathbf{I} = 20mA$ (20 milliamps) from A to B.

Example 2

The voltage difference between A and B is $5V - (-7V) = 12V$ . We don’t know the respective resistances of R2 and R3, but if we were told that the total equivalent resistance is, say, 1kΩ between A and B, then:
$\mathbf{I} = \frac{12}{1000} = 0.012$
Hence, $\mathbf{I} = 12mA$ from A to B. Again, because the path is undivided, this current is the same at all points along the path, including through each resistor, and the wire that joins them in the middle.

Example 3

In this example, there’s a different symbol at point B, which is the ‘ground’ symbol. It does not literally refer to the ground or “earth” beneath you, but rather indicates a reference point, which is always considered to be a relative 0 volts. Any points in a circuit that use this symbol are assumed to be directly connected to each other, and hence at the same reference voltage. Any other voltages are expressed as relative (positive or negative) to the ground 0-volt reference.

In this case, the voltage difference between A and B is $(-6V) - 0V = -6V$ . Again, we don’t know the resistances of the two resistors, but if we were told that the total equivalent resistance between A and B is, say, 2.4kΩ, then:
$\mathbf{I} = \frac{-6}{2400} = -0.0025$
Hence, $\mathbf{I} = -2.5mA$ from A to B. The negative current simply indicates that the charge is flowing in the reverse direction, since $A < B$ . Note that in this case, because the path is divided, we can’t say that the current across R4 (or R5) individually is the same as across the whole path. However, we can say that the current across the pair of them is still $\mathbf{I}$ . Ohm’s law also lets us conclude the following:

The voltage at the top point where R4 and R5 are connected, is -6V.

Likewise, the voltage at the bottom point where they’re connected is 0V.

Given this, the voltage across each of R4 and R5 is known to be -6V (looking downwards).

Hence, if we knew the resistances of R4 and R5 respectively, we could calculate their respective currents…

$\begin{aligned} \mathbf{I_{R4}}& = -6 / \mathbf{R4} \\ \mathbf{I_{R5}}& = -6 / \mathbf{R5} \end{aligned}$
…and we would actually find that $\mathbf{I} = \mathbf{I_{R4}} + \mathbf{I_{R5}}$ , which forms the basis of Kirchhoff’s Current Law, which is a topic for my next article.

Example 4

This circuit looks a little different from Example 3, but is basically the same configuration. Instead of being given explicit voltages for points A and B and having to find the difference, we can see that the voltage source BAT1 sets the voltage difference between these two points to 10V.

The ground symbol at the bottom doesn’t change anything, but establishes that we wish to consider this point to be our reference 0 volts, meaning that the relative voltage at A will be 10 volts. In larger circuits, this may be important to illustrate how multiple parts of the circuit are connected to the same baseline voltage.

If we were told that the equivalent resistance from A to B (through the network of resistors) was 80Ω, then the current from A to B is:
$\begin{aligned} \mathbf{I} & = \frac{10}{80} = 0.125 \\ & = \mathbf{I_{R7}} + \mathbf{I_{R8}} \\ & = \mathbf{I_{R6}} \end{aligned}$
That is, the current through the whole loop from A to B is 125mA, which is hence the current through R6, and hence the current through the pair of R7 and R8.

Conclusion

By now you should understand the relationship between voltage, current, and resistance, and be able to perform simple calculations involving the three. You should also understand the importance of a circuit, in allowing electricity to flow. So far we have looked at simple circuits that do not have a changing state. In the next article we will expand on this by learning how to analyse voltage, current, and resistance in more complex multi-path circuits, using Kirchhoff’s Circuit Laws.

anton.maurovic.com

AMMAURO #2: Linux VM for developers

AMMAURO #2 - Linux VM under Windows or macOS to enhance your development

My First YouTube Video: Inkjet Printer Teardown

AMMAURO #1 - Inkjet Printer Teardown

Good News! Feel good with positive news websites

No news is good news

Good news is better news

Positive news sites worth checking out

Lesser-quality positive news sites

Sites to avoid

Conclusion

See Also

Nintendo (NES) Gamedev, part 1: Setting up

Introduction

NES Development Environment

Installing on Windows

Installing on Mac OS X

Installing on Linux

Testing your emulator

Testing cc65 by building example code

Conclusion

Appendices

Mirrors of cc65

Building cc65 and FCEUX from source on Mac OS X

Building cc65 on Mac OS X

Building FCEUX on Mac OS X

Building cc65 and FCEUX from source on Linux

Alternative Software for NES Development

Alternative 6502 assemblers

Alternative NES emulators

Nestopia versions

Simple but Delicious Nasi Goreng

Ingredients

Method

Variations

Mac OS X Development Environment with Ruby

Summary

Checking existing environment

Installation Steps

Pre-requisites

Installing “Xcode Command Line Tools”

Installing Homebrew

Installing Git, and configuring for GitHub

Installing RVM

Install Bundler

Install optional stuff

Install ImageMagick

Install git-flow

Fix vim config

Install iTerm2

Install Sublime Text

Other stuff worth checking out

Troubleshooting

Tips for installing on Mac OS X 10.8 and above

Installing Xcode CLT via command-line

Conclusion

Wrangling Ruby and ImageMagick in Cygwin

Introduction

The Problem

My Specific Problem with Ruby and ImageMagick

My Solution

The Steps

Part 1: Install Cygwin

Part 2: Install devtools and RVM

Part 3: Install apt-cyg

Part 4: Enable OpenSSH server

Part 5: Fix vim config

Part 6: Set yourself up for GitHub

Part 7: Create an example Ruby project

Troubleshooting

More Packaging Designs for Seeed Studio

Maker Faire Banners

ADK Dash Kit - Box Art

Rainbow Cube, Ready to Shine - Box Art

Anton's Warm Chicken Salad

Ingredients

Method

Electronics, part 1: Analog Basics

Introduction

Fix `vim` config

Part 2: Install `devtools` and RVM

Part 3: Install `apt-cyg`

Part 5: Fix `vim` config