[Wordgrinder-users] HOWTO: Compile Wordgrinder 0.5.1 on Gentoo

[rtiangha <rti...@gm...>]

About a year ago I was trying to figure out how to get the latest
version of Wordgrinder to compile on Gentoo as I was encountering many
undefined symbol issues. I couldn't figure out how to fix them back
then, and it was only recently that I managed to figure it out. So I
figured I'd share what I learned in case anyone in the future runs into
the same problems, and also for my own reference in case I ever need to
do this again.

So, without further ado:

HOWTO: Compile Wordgrinder 0.5.1 on Gentoo

ASSUMPTIONS:
- You're building this on an x86 system. I don't have an ARM or PPC
machine to try this on and I'm not sure what the availability of the
various libraries are like on those platforms. YMMV.

PREREQUISITES:
- dev-lang/lua-5.2.3-r1 or greater
- sys-libs/zlib-1.2.8-r1 or greater
- luafilesystem 1.2.0 or greater

ISSUES:
- If you try to compile Wordgrinder 0.5.1 without any modifications (and
assuming you're using the stock Gentoo components for Wordgrinder's
software prerequisites), you'll encounter two errors during compilation:

1) The compile will fail when trying to compile the minizip components
due to undefined OF symbol errors
2) The compile will fail on detection of luafilesystem

The instructions below will show you how to deal with them.

INSTRUCTIONS:

1) lua-5.2 is currently hard-masked in Gentoo (the latest stable version
is 5.1.5-r3, as of this writing, and the latest version of lua 5.2 is
version 5.2.3-r1) so you'll need to unmask it (It also depends on
app-admin/eselect-lua-1 which is also hard-masked). You can do this by
adding the following entries to /etc/portage/package.unmask:

=dev-lang/lua-5.2.3-r1
=app-admin/eselect-lua-1

And then typing:

emerge lua eselect-lua

to install them.

2) While the version of luafilesystem in Gentoo's Portage tree should be
compatible with Wordgrinder-0.5.1, it gets installed in a weird place
(/usr/lib/lua/5.1.5, even if you're running and compiling against lua
5.2) such that when you try to compile Wordgrinder, it won't be able to
find it and the compilation will fail. So you'll need to symlink it to a
path that the Wordgrinder compiler will find it in.

The version in the Portage tree is also old (version 1.5.0 while 1.6.2
is the latest version). Unfortunately, there is currently no ebuild for
a more recent version, however you can use the dev-lua/luarocks utility
to install a more modern one (as well as any other lua module you may
need in the future).

You can install luarocks by running:

emerge luarocks

and then install luafilesystem by running:

luarocks build luafilesystem

3) The above will build and install luafilesystem onto your machine
(version 1.6.2-2 as of this writing), and it'll be properly linked
against lua 5.2 as well. However, the default luarocks installation
directory still won't be in a path that the Wordgrinder compiler will
find it, so you'll need to make a symlink for it to work. You can do
that by typing the following:

ln -s /usr/lib/lua/luarocks/lib/lua/5.2  /usr/lib/lua/5.2

which will make the luarocks lib directory the default lua 5.2 lib
directory. Suffice to say, you'll probably want to use luarocks to
install any other lua modules you might need in the future, rather than
use the ones in Gentoo's Portage tree. You'll probably get more current
versions that way too ;-)

4) Finally, you're going to get a lot of undefined OF symbol errors when
the compilation gets to the zip and minizip portions. There are some
issues with Gentoo's implementation of zlib that haven't been fixed as
of yet, mostly because it's the developer's opinion that it's an issue
that either needs to be fixed upstream or by individual software
maintainers who depend on the library. Suffice to say, it's a pain for a
regular Gentoo user who just wants everything to work.

You can get around this by adding -DOF=_Z_OF to the CFLAGS portion of
the Wordgrinder 0.5.1 Makefile to define how to handle those symbols. In
other words, find the override CFLAGS section of the Makefile (it's near
the top of the file) and make it look like this:

override CFLAGS += \
        -DVERSION='"$(VERSION)"' \
        -DOF=_Z_OF \
        -DFILEFORMAT=$(FILEFORMAT) \
        -DPREFIX='"$(HOME)"' \
        -Isrc/c \
        -Isrc/c/minizip \
        -Wall \
        -ffunction-sections \
        -fdata-sections \
        --std=gnu99

This is also the section where you can add any other CFLAGS that you
wish (ex. -march or -fomit-frame-pointer), although you'll want to test
to see if Wordgrinder will still compile and/or run stable, depending on
how aggressive your preferred custom CFLAGS are. You can also add -O2 or
-O3 here as well, however -Os is defined later in the Makefile, and I
can't remember which one will take precedence if more than one -O flag
is used during compilation.

Anyways, once you've done all of the above, you'll be all set to compile
Wordgrinder 0.5.1.

5) To compile Wordgrinder, simply type:

make

to compile Wordgrinder, followed by:

make install PREFIX=/usr

(or whatever PREFIX you want to install the bin directory to; for
instance, I use PREFIX=/usr/local to get the wordgrinder executable to
be installed into /usr/local/bin).

to install it.

Assuming you've done everything above, it should just work.

So to sum up:

1) Unmask lua5.2 and eselect-lua and then emerge them into the system.
2) Emerge luarocks and use it to install a more recent version of
luafilesystem.
3) Symlink the luarocks installation of its own library files to become
the default lua 5.2 system library directory so that the Wordgrinder
compilation will be able to see it later on.
4) Modify the Wordgrinder Makefile to define the OF symbols that the
bundled minizip instance depends on.
5) Compile and install Wordgrinder.

That's it. If anyone has any questions, feel free to post to the list,
but I've done the above twice on different systems and it consistently
works. There shouldn't be a problem, as long as you follow the instructions.

Cheers!