This page tells you how to download, install, and invoke the wikiCalc program. It includes links to the latest version.

NOTE: This page tells you how to download the wikiCalc program. It is currently at the 1.0 version. The code is being improved and supported as part of the SocialCalc project. For the latest release of SocialCalc, which has major improvements over the versions of wikiCalc available here, go to SocialCalc.org and the SocialCalc page on the Socialtext Open site. This site, with wikiCalc, remains for the original GPL-licensed code.

The wikiCalc program is released in two forms:

• For normal use on a web server, there are releases in both the normal GZ TAR file format common to Unix/Linux systems as well as ZIP format for Windows and others systems. The contents are the same. These releases can also be used for local execution on systems with Perl, including Mac OS X and Linux. They require Perl to already be installed on the computer.
  
  
• For local execution on a Windows system, there is a normal Windows downloadable "setup" file release. When executed, this release does a normal Windows installation. This release also includes a Perl language runtime so you don't need to already have Perl installed on the computer.

Before downloading, make sure that you know which version you need. If you are unfamiliar with wikiCalc, please first read "If you are new to wikiCalc..."

The source code is covered by the GNU GPL 2.0 license. The program is available for free and comes with no warranty of any kind. It can display license information when it runs. That information is also available in the source code and a copy is available on this web site in the Legal section.

Files for download:

Below you will find installation instructions for each of these forms of wikiCalc execution:

wikiCalc is available for download and installation using a traditional Windows Setup-style download (a ".exe" file to download and then run). The Setup file, when run, will install the needed components on your system: wikicalcwin.exe and several data files. It will also create a shortcut to wikiCalc in the Windows Start Programs menu. wikiCalc is written in Perl but you don't need to have a Perl runtime installed on your computer. When you run the installed wikicalcwin.exe program it temporarily extracts from itself the compiled Perl code along with a Perl runtime and then runs that code. When you exit wikicalcwin.exe the extracted files are deleted.

If you are upgrading from an earlier version of wikiCalc, you should first uninstall the old version which should leave your data intact (though it is prudent to backup the entire contents of the wkcdata directory just in case...). The new release will use the existing data, updating formats if necessary automatically.

To run the program, just use the shortcut it puts in the Start / Programs menu or double-click on the wikicalcwin.exe file that was installed. It should be run with the working directory the same directory as where the program resides.

When wikiCalc starts running it should show up as a "sprout with roots" icon in the system tray (usually in the bottom right of the screen). To interact with the program, use a web browser to view the URL "http://127.0.0.1:6556". You can get the program to launch a browser viewing that page by double-clicking on the tray icon, or by single-clicking to bring up a menu and then selecting the "Launch UI" menu item. Exit the program by using the "Quit" button in the program's UI shown in the browser. Alternatively, use the "Shutdown" menu item on the tray icon.

If you have a firewall running on your system (such as Windows Firewall), you may see a warning that wikiCalc is attempting to accept Internet connections. Do not block this (e.g., with Windows Firewall click on "Unblock"). The installer tries to add wikicalc.exe to the exceptions list so this won't happen (you can make it more secure by adding a restriction to only accept requests from your LAN, etc. -- see the Windows Firewall documentation). The wikiCalc program works by communicating with your browser by running a simple local web server. The UI runs in the browser. wikiCalc should only accept requests from your local machine, not from other computers connected to your LAN or the rest of the Internet (though how well this has been tested in unknown).

Uninstall: To uninstall wikiCalc use the normal Windows Control Panel "Add or Remove Programs" function. This will delete the installed files and remove the shortcut on the Programs menu. It will not remove the "wkcdata" directory (created in the directory where you installed wikiCalc) and all of the data you created when using wikiCalc. You may delete that directory and its contents manually if you want.

For further information about setting up wikiCalc and initial use, see "Starting to use wikiCalc".

The wikiCalc program is written in the Perl computer language. In order to run, it requires a copy of the Perl language system which is commonly found preinstalled on most Linux and similar systems, as well as on most web servers.

These instructions are oriented towards users with technical experience who are comfortable with configuring and running programs from the command line.

The system requirements are: Internet connection, 2MB+ disk space, Perl language system that includes the library modules: LWP::UserAgent, Net::FTP, and Time::Local.

If you downloaded the archive file, you can extract it into the "wikicalc" subdirectory of the current directory with the command "tar -xvzf wikicalc-1-0.tar.gz". Alternatively, the ZIP version can be unzipped using a variety of utilities.

You run the program locally by executing the command:

perl wikicalc.pl

You can give it the option value -h to see a list of options.

When executing the program, you can exit before it's finished by pressing Ctrl-C.

After you start the program running, you interact with it by accessing the URL it lists. By default, you need to open the following local URL with your browser:

http://127.0.0.1:6556

You normally quit by using the "Quit" command in the user interface.

If the program displays an error message when run complaining about a missing module, such as LWP, or LWP::UserAgent, you can get the missing module from CPAN. Most Perl installations include the CPAN.pm module to automate this downloading process. See the Mac Perl Setup description to get an idea how to use CPAN.pm. CPAN.pm documentation should be available on your computer by using the command "perldoc CPAN".

For further information about setting up wikiCalc and initial use, see "Starting to use wikiCalc".

Notes for Mac OS X users: The system requirements include: Mac OS X version 10.3 and later, Apple Safari web browser or equivalent such as Firefox (Internet Explorer sometimes has problems).

Make sure that you have Perl on your Mac and that you have the correct packages installed. See the ListGarden Mac OS X 10.3 Setup page for step-by-step instructions. Once you have Perl installed, you can then run Perl programs from the command line in a Terminal program window by executing "perl programname" (or just by executing the ".pl" program directly if the file permissions include "execute"). Access with Safari or a similar browser. If the program displays an error message in the Terminal window when run complaining about a missing module, such as LWP, or LWP::UserAgent, see the ListGarden Mac OS X 10.3 Perl Setup page for documentation about getting the correct Perl packages. You may also need to add HTML::Tagset.pm on OS X 10.4. Some versions of 10.4 make Safari have periodic problems accessing wikiCalc -- upgrading to the latest version of Safari seems to fix it.

To make it easier to run the program, you can create a shell script to execute it and invoke that. Run the script by double-clicking on it or set it up to run whenever you restart the computer (for example, by having the script in your System Preferences / Accounts / Startup Items list). For example, the script could contain:

cd directory with program and files
perl wikicalc.pl

Uninstall: To uninstall the program delete the files you downloaded and extracted as well as the directories and data files created.

The wikiCalc program is written in the Perl computer language. In order to run, it requires a copy of the Perl language system which is commonly found preinstalled on most Linux and similar systems, as well as on most web servers.

These instructions are oriented towards users with technical experience who are comfortable with configuring and running programs from the command line or setting up web CGI programs.

The system requirements are: Internet connection, 2MB+ disk space, Perl language system that includes the library modules: LWP::UserAgent, Net::FTP, and Time::Local.

If you downloaded the archive file, you can extract it into the "wikicalc" subdirectory of the current directory with the command "tar -xvzf wikicalc-1-0.tar.gz". Alternatively, the ZIP version can be unzipped using a variety of utilities.

Move all of the files into the directory where you want wikiCalc to run. This could be, for example, in the cgi-bin/wikicalc directory.

You access wikiCalc when run on a server by executing the wikicalccgi.pl program with a browser request. (See the note below about mod_perl.) For example, if it was installed in cgi-bin/wikicalc, you would access wikiCalc with a URL like:

http://www.you.com/cgi-bin/wikicalc/wikicalccgi.pl

Note that the wikicalccgi.pl file must be executable, such as by having its permissions set to 755. Also, if you are installing wikiCalc in a new directory, be aware that it needs to have permission to create and modify the data files in the working directory and below as well as where it publishes the HTML. Therefore, make sure that when run by the web server daemon wikiCalc has permission to create files in the directory (for example, that the directory is in the web server's group "apache" with write permission to the group).

It may be best if you start by manually creating the "wkcdata" subdirectory before running wikiCalc (it will try to create it if it's not present) and set the permissions so wikiCalc can write to that directory. wikiCalc keeps all of its data in this directory. You can have the directory in a place other than the working directory by setting the $WKCdirectory value in the WKCString.pm file.

It is also important to make sure that the directory where wikiCalc will publish HTML files exists, unless you are only doing "live" viewing and not publishing HTML. Also, make sure the program has write access to that directory.

The first thing you should do after you have installed wikiCalc is to use its administration system on the Tools tab to set up an admin user with a password and set the "Require Login" setting to "Yes".

For further information about setting up wikiCalc and initial use, see "Starting to use wikiCalc", especially the "Manual Setup" section.

Security Note: Before installing wikiCalc for remote access, make sure that you are aware of the security issues it may raise. For example, there are many settings that let the user save the result or read from anywhere the program has access. When run remotely, you may want to protect the program with a password (such as by using .htaccess) so that only authorized users can run it. For this reason, install and use remote access with caution. This is especially true of the runtime helper application WKCcallableUtilities.pl. This program is set up to be able to make HTTP requests anywhere on the Internet from your server. Unauthorized access to it (and maybe even the "Live View" functionality) may not be something you want, so do not set "Execute" access on this file, or any file other than wikicalccgi.pl, without careful additional thought.

wikiCalc has a user administration system built in (it's on the Tools tab). You can use that for simple security (and should use it in all cases if more than one user will be editing). You should set at least one user as an Admin user -- non-admin users should not get access to the user administration system. In general, it is not a good idea to give all users admin access. Note that the security code is simple and was not heavily tested.

Performance and mod_perl: wikiCalc is not a small program and on many systems when it is accessed as a CGI script it is restarted on each request. This adds significant overhead, often as much as a half second or more of cpu time in addition to the cpu time it uses when run (which can be as much as a second or more on a large recalc or redisplay) depending upon your server cpu speed. This means that on a shared server wikiCalc could be a heavy load. On a dedicated machine it will do quite well. On some systems you can leave wikiCalc running and reuse it for each request just like when it is run on the desktop. This is done with mod_perl. To run wikiCalc using mod_perl use wikicalcmodperl.pl instead of wikicalccgi.pl. Note that currently only the older version 1 of mod_perl is supported. For information about version 2, see "wikiCalc and mod_perl version 2").

Uninstall: To uninstall the program delete the files you downloaded and extracted as well as the directories and data files created.