README for Aubit 4GL 32 bit Linux Virtual Machine

Contents:

• Purpose of this document
• For Whiseguys & Know-it-alls
• Purpose of this VM
• History
• Content of the VM
• Obtaining the VM
• Use of the VM
• Important locations inside of the VM (guest) OS
• Quick start
• Feedback? Questions?
• Networking
• Starting and stopping databases
• Misc notes
• FAQ
• Known issues
• To-Do
• Thanks
• Things to see and do next

...is to help you quickly start using this VM. It is NOT intended to teach you basics of Linux, SuSE, Aubit, 4GL or any other software provided in it. For that, please consult appropriate web sites and manuals.

• Get & install Azureus BitTorrent client
• Get Aubit VM via Torrent: (Size: 1.3GB) Click here
• Get & install VMWare free Player or Server
• Unpack downloaded VM (Size: 3.9GB), open with VMWare, click 'play'
• Enjoy, keep on reading (optional)

There are several common scenarios for using this VM:

• To quickly evaluate Aubit compiler and tools without the need to install any software, or affect existing setup of physical computers
• To provide fully featured environment for development of Aubit 4GL compiler and associated tools
• To enable working in Linux environment, when user has no physical Linux installation, but has another OS that can execute VM (like Windows)
• For demonstrations and presentations on sites that have no appropriate environment, and to provide consistent state of programs and data for presentation
• To enable developers of 4GL applications to work on there 4GL code without having to spend time configuring Aubit tools and there dependencies correctly
• To provide unified and consistent environment among a team of developers, that is easy to replicate, and therefore easy to debug software in
• Provide access to 32 bit platform for people with only 64 bit systems
• Many other, as you will soon discover

• 23-10-2006 - (version 0.5) Initial release

This VM contains ALL Aubit compiler dependencies, options, and many 3rd party tools. All software in this machine is OpenSource software released under one of OpenSource licenses, that permits it's re-distribution, or a commercial/closed source software
that explicitly permits re-distribution.

Instead of listing all installed software, check the full current list using your favorite RPM package manager (try Start->System->Yast->Software Management)

Also see Aubit's "./configure --help" for a list of dependencies and options Aubit knows about (most of them anyway, as some can't be turned off)

Some (minority) software was installed form source code or binary tarballs, and will not show in RPM list; This includes, but is not limited to mpz pdflib poplib cint sxml libsmtp iodbc, and more. Most of it was installed using corresponding Aubit 'make install.xxx' command.

As for database engines, you will find PostgreSQL 8, PostgreSQL 7.4 with Informix compatibility patch applied, SQLite, MySQL and Ingres. SAP DB (MySQL MaxDB) client tools are installed, but not the database engine.

Other installed SW includes jEdit IDE, LyX documentation editor, Glade designer, Java, TomCat, SQuirell SQL client, DBdesigner 4, and of course core SuSE Linux.

More or less any other software (of any remotely significant size) was removed from this installation of SuSE 10.1 to limit size and download time. (Hint: 10Mb is not a 'remotely significant size' when talking about anything above 1GB in size)

If some favorite development tool of yours is missing, please let us know, and it may be included in the next release.


Initially, this VM is only available via BitTorrent. I use Azureus, you may choose any BitTorrent you like.

Download size is 1.3 GB approximately. My server is on modest ADSL line, so until several downloaders pull most parts of it from my box, things will go sl...ow...ly… This is the nature of BitTorrrent file sharing protocol - when more people share same file (complete or partially downloaded), download speeds go up for everyone.

If you can volunteer hosting for Aubit VMs, please let me know. It will be greatly appreciated.

MAKE SURE YOUR BITTORRENT PORT IS OPEN - IF IT IS NOT, NOBODY WILL BE ABLE TO DOWNLOAD FROM YOU, AND YOUR DOWNLOAD WILL BE USELESSLY SLOW. Azureus has a wizard that checks your ports - please make sure you can confirm the port is open before starting the download.

Use this Torrent: Torrent


Tracker is: http://falout.org:6969

After the download is complete:

• DO NOT CLOSE YOUR BITTORRENT APPLICATION! LEAVE IT RUNNING, SO THAT OTHER PEOPLE DOWNLOADING IT CAN CONTINUE DOWNLOADING IT FROM YOU! This is the nature of BitTorrent file sharing protocol - all the files, or there peaces,

are immediately available for download to other people trying to download the same file.

• DO NOT MOVE OR UNPACK THE FILE YOU DOWNLOADED IN THE PLACE IT WAS DOWNLOADED TO! If you do, it will be lost for people trying to download it from you. Instead, make a copy of it somewhere else, and use that copy to unpack the VM.

Both of above items will be crucial for my ability to make this VM available to everyone interested. Remember, I have limited bandwidth, and unless the download demand is distributed between all BitTorrent clients, my modest ADSL connection would have to serve all of it, to everyone. Which would simply not work with a file of this size.

I thank you for sharing your bandwidth.

Now that you got it, make a >>COPY<< (do NOT move it from the place it was downloaded to) of then downloaded file, and unpack it:

• On Windows, almost all archive managers should do the job (WinZip, TugZip, ZipoGenious, WinRar,...)
• On OSX, I don't have a clue :-)
• On Linux/Solaris, use something like "tar -xjf <filename>.tar.bz2"

Two things to consider when calculating free disk space needed:

• VM compresses really well, and despite archive being only 1.3 GB at the moment, unpacked size is 3.9 GB. Therefore, assume a minimum of 3 times the size of VM archive as needed to unpack, but...
• ...not enough to run! This VM has been "shrinked", and it's virtual disk will actually expand with use. (See VMWare web site if you are curious about what's going on). In general, add another GB for comfortable use.

If you don't have VMWare already, get it from http://www.vmware.com. Look for "Free virtualization" link, and choose between "Player", which is a basic VM execution environment and cannot create new VMs, or "Server", which is more capable and of course, larger download.

For folks new with VM, I do recommend reading few pages of the manual, to better understand what is going on here. For some folks it may be obvious, but let me emphasize that the fact that this VM is based on Linux, (e.g.. the 'guest' OS is Linux) does >>NOT<<
mean that you need to run it on Linux 'host' OS; in fact, you can run it on >>ANY< operating system that has a VMWare execution environment available, which includes Linux, Windows, Solaris, and OSX at the moment.

Also, when downloading VMWare, you will choose the version for YOUR OS, not the one for OS of the VM (which is in our case
Linux). For example, you will download VMWare Player for Windows, if your PC's OS is Windows, VMWare Player for Linux if your PC's OS is Linux, regardless of which 'guest' OS is inside the virtual machine itself.

Please see VMWare web site for hardware requirements. By default this VM has 710 MB of RAM allocated to it, and after literally months of uptime, it uses 70% of that for application data, and 14% for disk buffers and disk cache each, without using ANY SWAP in the guest OS. This is how it should be.

Therefore, if you have 1GB or more RAM in your host computer, this should work well for you. If you don't, your host (or guest, or both) will start swapping, which will slow things down, but should still work. With 500 MB of RAM, you will probably want to reduce RAM available to the VM. It may or may not work. But with today's prices of RAM, I have just one meaningful advice: Buy more RAM. 2GB should this days be on every machine used for software development purpose.

After installing VMWare, run it, and from File menu choose Open. Navigate to the location where you unpacked Aubit VM, and choose to open VMWare configuration file found there (.vmx). Configuration will open, showing various components and settings available in this VM, like hard disk, network interface, etc.

Click on the big green "Play" icon, and Aubit VM will boot, like any other operating system, inside your VMWare window.

If you are prompted about VM changing location, DO NOT click on "create" button. VMWare recomends it, but it is pointless in this case (as there is little to no chance of you running this same VM more then once, so you do not need a unique identifiers forr each to distinguish between them) and if you do, Ethernet interface MAC address will change, which will force you to re-configure networking (see how to do that, if needed, under "Networking" section)

Default user into which this VM boots automatically, is user named "aubit" It is recommended that you use it for all development, and resort to using "root" user only for administration.

ALL passwords are set to "aubit"; root, MySQL users, PostgreSQL users - ALL. Database user 'aubit' is typically already created, and default admin users (postgres, mysql) all have password 'aubit'.

• /home/aubit - home directory of "aubit" user, and also home to user level aubitrc configuration file, .aubit4gl.acl ACL file, and all other Linux user settings
• /home/aubit/aubit4gl - Directory where by default compiled Aubit binaries get installed. They are already there, so you can immediately start using Aubit compiler.
• /usr/src/aubit - Default location for ALL Aubit project source code. When you download this VM, this location is empty, apart form the check-out script. This is done because correct content of the source code tree for you will depend on weather you have committers login to Aubit CVS or not.

If you do, you need your own 'named' CVS check-out, to be able to commit back to CVS.
If you don't, you need anonymous code, as you would not be able to update CVS tree checked out under developers login. So, to prevent forcing everyone to download megabytes of (for them) useless code, you should check out your own.
For this purpose, a script get_4gl_cvs.sh is provided in this location. If you run it without any options, it will check out default components of Aubit and Apps4GL CVS repositories.
It can also check out only selected components, as well as do a check out using a developers log in. Try 'get_4gl_cvs.sh -help' for details.
NOTE: If you decide to check out everything, be aware that this will take a while, depending on your Internet connection, and current mood of SourceForge servers. Be patient. It may take 10-30 minutes. You will see files as being checked out (downloaded) so you will know what's going on.

• /etc/opt/aubit4gl - directory of the system global aubit configuration file (aubitrc) By default, this is created only if you install Aubit compiler as user 'root'. As I don't do that, it is empty or does not exist as supplied
• /home/aubit/Desktop/Test results - Folder contains summary results of test ran in aubit4gltest tree, as I last executed them
• /bin/custom/aubitconf - file automatically read by ./configure, that contains default setting for configure (like --with-xxx= flags) so one don't need to re-type them each time. Feel free to adjust it for your preferences of what gets compiled or not (see './configure --help' for options)

Now that you have Aubit VM running, click on the terminal icon on the tool bar (picturing monitor with a ">_" in it)

In terminal emulator menu, select Bookmarks->/home/aubit/aubit4gl/tools/test, or just cd into this directory.

Type "make"

Follow instructions shown at the end of make execution, to launch 'hello' demo program.

Want GUI? Edit aubitrc, or "export A4GL_UI=HL_GTK", or maybe just:
A4GL_UI=HL_GTK aubit ./hello.4ae

Do't want GUI? Edit aubitrc, or "export A4GL_UI=TUI", or maybe just:
A4GL_UI=TUI aubit ./hello.4ae

You can run command 'aubit configurator' to familiarize yourself with configuration options of Aubit compiler, and set default options (UI, database, ...) to your liking. All options you will see there can be passed on command line (like in above examples), set in environment (export XYZ=123), set in shell start-up scripts (something I personally discourage) or in one of aubitrc configuration files.

Got that running? Great. Where do you go from here will depend on what you want to do, and there are too many possibilities for me to cover them all. In general:

• If you want Aubit source code (to do Aubit 4GL compiler development, or maybe just to stay up-to-date the regular basis with fixes and improvements done by developers) cd to /usr/src/aubit and check it out (pun intended!). See under "Important locations" for details - a script to do this for you automatically is provided.
• Grab some of your 4GL code and compile it using Aubit. If you want to check out others 4GL code, try http://apps4gl.sourceforge.net
• Start JEdit (Big "JE" icon on toolbar) and explore various projects already defined in "Project View" pane (Note: You need to check out the source code first. After you do, you may want to right-click on projects listed under "All Projects" and select "Re-Import files" to refresh files list - "File filter for importing" should be set to "Use CVS or SVN entries file") JEdit is extremely powerful tool and explaining it's use is beyond the scope of this document. Check out built-in help, and http://jedit.org for more info) If you don't' like JEdit, you can of course always use any other environment of your preference, like vi (...do you really still...?) or Kate, or install your own preferred tools.
• If you are new to Aubit, go to aubit4gl.sourceforge.net and take a look around. Download the manual and read it. Join the Aubit users and developers community by subscribing to Aubit mailing list(s). Mailing lists are also the primary support channel for Aubit project, so all your questions should go there too.

We do appreciate your feedback. Please send it to one of appropriate Aubit project mailing lists.

Please note that with the goal of minimizing spam received by subscribers, ALL Aubit project mailing lists require posters to be subscribed to the list they are posting to. See http://sourceforge.net/mail/?group_id=32409


You will want it; So make sure your VMWare host configuration is appropriate (that it allows VM to connect to your host or network in most appropriate way) and make sure VM got it's IP address and default router address from your DHCP server (Hint: this Linux installation is configured for DHCP). In most cases this will happen automatically; if it did not, try refreshing DHCP by running 'su -c "service network restart"'. Check out then output of "ifconfig" if in doubt.

If that did not work, then read on...

When VM is copied/moved, user is prompted to keep or create internal VM ID. Although it is advisable to create new one, it has a side effect. VMWare will automatically change hardware (MAC) address of virtual Ethernet interface to that machine, to avoid possible
conflict with the original VM. This may make guest OS think that this is a new interface, and consider it without configuration, and therefore do not start the interface when booting. And the configuration that does exist, now points to no longer existing MAC address,
and is therefore simply ignored. Silly, right?

Thankfully, solution is simple; either keep the VM ID when prompted, or after VM finished booting, open "Network Interface" item in Yast (Start->System->Yast->Network Devices->Network Card), and configure supposedly "new" interface. Usually just keep the defaults, and this will configure everything for DHCP and restart network support. If needed, you can specify details (IP address, default gateway, DNS, etc) manually.

Hint #2: SuSE don't like when you mess with it's configuration files. Make sure you tried all you can using Yast, before resorting to hacking config files. This is very rarely really needed, so try to resist ;-)


Before you can use a database engine (RDBMS) for Aubit 4GL programs, database engine has to be running. As I have no way of knowing which one is (PostgreSQL 8, PostgreSQL 7.5 with Informix patch, MySQL, etc...) is of interest to you, no database is automatically started, to preserve RAM.

(Note - all rc scripts can be invoked using command 'service servicename', where servicename is the name of rc script under /etc/rc.d/) In most cases you will need to become super user (root) to start them. (Hint: su -c "service ....")

• Ingres - 'service ingresII start|stop|status|...'
• MySQL - 'service mysql ...'
• PostgreSQL 8 - 'service postgresql ...' or 'pg_ctl ...'
• PostgreSQL 7.4 with IFX patch - 'pgifx_ctl ...'
• SQLite - no startup needed - SQLite is just a library

• Use VM snapshots to your advantage. If you are about to make a change that you are not sure of the impact of, take a VM snapshot; then, if (when!) things go wrong, just revert the VM to the snapshot point, and nothing happened. Oh joy, where was it when I was younger....
• Manage VM memory appropriately. Swap is NOT disabled in this VM. MONITOR YOUR RAM USE! Allocate more RAM to the VM in VMWare control panel if needed, and if this exceeds your physical RAM in the host, your host will then swap to disk. Which is probably going to be faster then VM swapping on virtual disk inside VM, but jury is still out on that issue (which is the reason I decided to keep swap partition in guest for now. This has the unfortuante effect of making you download 2 gigabyte of useless data when downloading this VM, but as you can see from download size, it does compress rather well. I'll base my decision on wheather to keep it in the future releases on your feedback)
• If you feel like releasing the Aubit VM of your own, check out AubitVMpackagingNotes
• MaxDB notes:

maxdb admin = DBADMIN/aubit db name = MAXDB1
group name for database programs = sdba
owner name = sdb
database data: /var/opt/sdb/data
programs: /opt/sdb/programs

• If you experience repeating characters in guest OS, try:

xset r rate 800 2, or
xset r rate 500 10


Q: Can this VM be smaller?

Yes it can - if you don't need the functionality :-) Remember the purpose of this VM. It is primarily DEVELOPMENT. So if you can tell me which peaces can be removed without compromising this goal, I'll do it.

At some point in time I may create a significantly smaller VM for a different purpose, like demonstrating 4GL applications and compiler, with limited set of options. This should be reasonably easy to do by simply removing software already installed in this VM, if you feel like trying it yourself.

Q: Can we have a LiveCD instead of VM?

Can you run a LiveCD without shutting down your computer, which you are probably using for more then to watch screen saver on?

Can you pack all of this VM on the CD? If not, does everyone have DVD burner?

So in short, for stated purpose - no. At some point in time I may create a LiveCD for a purpose of demonstrating Aubit, but please do remember - ONE CANNOT RUN A DATABASE ENGINE FROM A READ-ONLY FILE SYSTEM. And surprise - CD-ROM and DVD-ROM
is a READ-ONLY media! So without ability to write somewhere on the host machine, any LiveCD/DVD is useless for the purpose of database development tool/compiler such as Aubit 4GL. And this requirement will make it far less immediate and simple to use then a VM.

Q: Can I get it without using BitTorrent?

Not at this time. I do not have the bandwidth to serve all of it to everyone, and SourceForge does not accept files of this size. If you know of a kind person/company willing to provide hosting for it, then yes, in the future maybe.

Q: Application/library xyz that I like/use/need is missing;
Functionality xyz is not working; xyz is not configured the way it should be;
I know a better way to do xyz.

Let me know, by reporting it on appropriate Aubit mailing list

Q: Can we have a Windows based VM?

No. Windows is a commercial product, and I cant give anyone copy of Windows licensed to me, virtual or not. (I do have one and use it for all Windows development) I did attempt to use ReactOS for this purpose, but could not manage to get CygWin running on it. It seems that current level of compatibility of ReactOS with Windows is still incomplete. It must be a hard thing to do, emulating all this legacy bugs and 'undocumented behaviors' :-) Maybe in a year or so I'll try again.

I was also considering installing a Win32 GCC tool chain on Linux, and even installing native Windows tools needed (CygWin, MinGW, ...) into Linux under Wine, but his seems to me as the solution that defeats the primary purpose for the Windows environment. Which is in most cases that people that want it, are comfortable only with Windows. Such users would quite probably get completely lost in mixed environment of Linux and Wine, no matter how well it works.

Personally, I do see a Windows port of Aubit tools as needed - as a run-time platform, but cannot imagine for the life of me who would prefer doing DEVELOPMENT on Windows. I certainly do not know of any DEVELOPERS that are equally skilled in Windows and Linux, that prefer Windows for such task.

Maybe this is a good opportunity for folks that are asking for Windows VM, to do a bit learning, and expand there horizons.

Q: Can we have a VM for other VM runners, not only VMWare?

We can, but I'm not sure why. What would the advantage be?

Q: What are the limitations/shortcomings of using Aubit in virtual environment, compared to a traditional install on the host PC?

In short, I'm not sure there are any (relevant or significant) limitations;

As for performance, there is a bit (<5%) overhead that this kind of software exhibits when running in VM, compared to running natively; I would probably not run a terabyte sized instance of Oracle database that regularly gets hit by hundreds of users,
on a virtual filesytem, even if I know some very serious vendors that do.

If you have one of the latest CPUs that support hardware assisted virtualization (AMD Pacifica (Revision F and up), Intel "Intel Virtualization Technology") your overhead is probably <1%, with disk I/O maybe the only factor to mention at all. And after all, you can always install database server on physical machine, and continue running programs in VM, that connect to that db server over the
network. Or set database file on a physical partition, while still running it in VM.

Obviously, you are sacrificing RAM to run 2 operating systems (one on the host, one in the VM) instead of one, which will 'cost' you about 200-300 Mb. I personally think that this is just about irrelevant this days. If you disagree, maybe you need to check current prices of RAM.

One thing that does annoy me is that I cant spread VM over multiple monitors, which is a very useful feature. But I just open a VNC sessions on the other monitors to the VM, and that does work fine, to a degree (Cant D&D, C&P...)

In summary, the advantages of being able to download pre-configured environment of this kind, instead of spending days/weeks setting it all up, outweigh above by a significant margin alone. Add to this all the benefits of manageability and flexibility that VM concept brings, and I cant think of anything else I would use for myself. In fact, this was probably my last installation of Aubit
environment, for a long, long time to come.

Q: What is the MINIMUM hardware you recommend for this VM?

VMWare supported CPU > 1.5 GHz, 1 GB RAM, 10 GB free space on HD. Also read VMWare performance tips.

Q: What hardware do you run this VM on when developing?

Tyan Tiger motherboard with 2 * dual core AMD Opteron CPUs @ 2.8 MHz, 4 GB RAM, Linux (Suse 9.1 64 bit) on software RAID5 hard disks (4 * 250GB)

Q: How often will this VM get updated?

Probably not for 6 months or so; All Aubit source code in the VM, can of course be updated as often as you like, and user can install (or remove) any software he likes, so there is no reason for anyone to have to wait for me to update it. Hopefully, the need to update or add new software will probably not arise too often. Unless we discover a significant issue in this one... ;-)

Instead, I am considering to create a 64 bit equivalent of this VM. If you have interest in seeing this happen, please do express your interest on Aubit mailing list. Please note that in order to run 64 bit guest OS in VM, you need to have a 64 bit CPU, and run a 64 bit host OS.

• sf-release script core dumps
• SuSE updates not working (register)
• iodbcadm-gtk wont run
• iiodbcadmn wont run
• Perl CPAN does not seem to work

Changes/enhancements planned for future releases of this VM:

• configure odbc.ini for all databases
• Finish configuring Jedit for full functionality
• Configure data connections for DBdesigner 4
• Configure JDBC drivers for SquirrelSQL
• Considder droping swap partition and disable swapping inside guest OS
• Add SQL tools - Squirrel SQL , converter, PG/MySQL/SQLite admin tools
• Add more databases? (MaxDB, FireBird, Oracle XE, Enterprise DB, DB/2 Express-C, Sybase Express Edition,...)
• SQL tools: BabelQL, SQL Edge, SQL Fairy,...
• InfoFlex/Querix/4Js?
• Install gdb GUI
• Make VM available via rsync for quick updates
• Suse auto update? Inst Source config? wget http://www.ncaabbs.com/~gts/suse-repo-script-x86-64.sh

Without the work of Mike Aubury, there would be no Aubit compiler, and therefore there would be no Aubit VM.

A number of contributors helped us along the way in Aubit project, by reporting bugs, writing new code, donating code, enhancing functionality and writing documentation. You know who you are, and I sincerely thank you for your contribution.

Without Aubit user's support and help, there would be no Aubit project. Use it, share it, report bugs back to developers. Help us improve it for you and us all!

To all the commercial companies using Aubit tools, thank you for believing in us, and in the x4GL programming language.

From Linus Thorvalds, to Eric Raymond and other giants of OpenSource and Free Software movements, we would be nowhere without you guys! To everyone at projects like GNU GCC, PostgreSQL, MySQL, GTK and all others that I simply don't
have the space to mention by name, our hats off to you all!

Thanks to SuSE for a wonderful distro, and to VMWare for having the balls, and the software that just works.

Thanks to everyone at Informix for inventing the I-4GL programming language, and a speciall personal thanks to Jonathan Leffler, who helped countless 4GL programmers, including me, in the days when they had more questions then answers.

"We are building the force of extraordinary magnitude. You have our gratitude!"

• Read the Aubit compiler manual
• Browse the Aubit web site and Wiki to learn more about development process and available software
• Join the Aubit project mailing list

Have fun,
Andrej Falout