Wing IDE Reference Manual
   
Wing IDE Reference Manual

Version 1.1b7-2


next up previous contents
Next: 2. Customization Up: Wing IDE Reference Manual Previous: Contents


Subsections

1. Introduction

Thanks for choosing Archaeopteryx Software's Wing IDE! This manual will help you get started and serves as a reference for the entire feature set of Wing IDE.

The manual is organized by major functional area of Wing IDE, including the project manager, text editor, source code browser, and debugger. Several appendices document the entire command set, provide pointers to resources and tips for Wing and Python users, and list the full software license.

The rest of this chapter describes how to install and start using Wing IDE. If you hate reading manuals, you should be able to get started by reading this chapter only.


   Throughout this manual, key concepts and important notes are highlighted in the same way as this paragraph. If you are skimming only, look for these marks.

1.1 Licenses

Every copy of Wing requires either an evaluation (demo) or a paid license to run, in addition to an installation made from the download or CD media. Demo licenses can be obtained from our web site at http://wingide.com/wingide/demo and permanent licenses can be purchased in the online store at http://wingide.com/order. When Wing is first started, it will ask to copy your license file into place.

Evaluation licenses may be used for 30 days to evaluate Wing, and allow all features to be used. Paid licenses may be used with any version in the 1.x series and allow access to the source code via wingide.com. Licenses may be single user licenses, which allow one named user to use Wing, or floating multi-user licenses, which allow up to a set number of users to use Wing at the same time.


1.2 Installing


   Quick start on Linux:

To install Wing for individual use on an RPM-based system, obtain wingide-1.1b7-2.rpm and a license file from wingide.com, then run rpm -i wingide-1.1b7-2.rpm as root.

For single-user installation on systems without RPM, obtain wingide-1.1b7-2.tar.gz and a license file from wingide.com, unpack the tar file with tar -zxvf wingide-1.1b7-2.tar.gz, cd to the wingide-1.1b7-2 directory, type wing-install.py, and answer the questions to specify where the program files should go.

After installing, the command wing should start the IDE. You may have to modify your path if you've installed the executables in a directory that isn't already on your path. You may also have to open a new shell or request that your shell rescan the disk for executables (for example, with rehash under tcsh).

Once Wing starts, follow the instructions to locate your license file (Wing will be copy it into place), accept the licensing agreement, and set up your initial preferences.



   Quick start on Windows

Ensure that Python 1.5.2, 2.0, or 2.1 is installed on your system. Obtain the wingide-1.1b7-2.exe installer package from wingide.com and execute it on your system. After installing, run wing by selecting Wing from the Programs:Wing IDE section of the Start menu.

Once Wing starts, follow the instructions to locate your license file Wing will be copy it into place), accept the licensing agreement, and set up your initial preferences.


1.2.1 Supported Platforms

This version of Wing is available for Microsoft Windows and Linux.

The Windows product has been tested on Windows 98se, NT4 SP3, and 2000 SP1.

The Linux product has been tested on RedHat 6.0, 6.1, 6.2, and 7.1; Suse 6.2, 6.4, and 7.0; Caldera 2.4; Mandrake 6.1, 7.1, 7.2, and 8.0; and Debian 2.2. On RedHat 6.0, you must install Python 1.5.2, 2.0, or 2.1 and use that to run your debug program and the tar file installer (if RPM is not used), instead of the default Python 1.5.1 installation that comes with RedHat 6.0. On Suse, you may need to install the gmp and python packages, or install Python from source, since Python is not installed by default here.

RedHat 5.2 is known not to work and there are no plans for supporting it.

1.2.2 Prerequisites

In order to use Wing, you need to have the following third party materials installed on your system:

For Linux

Most users already have these available. The RPM distribution will check for most of these dependencies. If you are installing from tar, you must verify manually that you have these installed already, as there is no automatic dependency checker in the tar file installation.

By default, Wing uses Adobe Acrobat Reader and Netscape Navigator for viewing the manual and other items in the Help menu. Other PDF viewers and web browsers can be used instead; see section 2.2.7 for information on configuring these.

Gnome users should note that Wing comes with its own copy of GTK 1.2.8 that has disabled use of themes. As a result, Wing ignores your theme settings and always runs as if the Default theme were selected. This avoids problems with with some versions of GTK and some themes. You can get Wing to run against your native installed version of GTK, and to use themes, in one of two ways: (a) specify --system-gtk as the first command line argument for the wing startup script, or (b) rename or move WINGHOME/bin/gtk-bin (be sure to retain a copy in case your system's version of GTK is one of those that causes frequent crashing in Wing).

For Windows

If you have ordered the CD, most of the above are available in the 3rdparty directory. They are also available in the download area of our website at ftp://archaeopteryx.com/pub/wingide.

In order to view the PDF versions of the Wing IDE manual, you must also have a PDF viewer such as Adobe Acrobat Reader 4.0.5 installed and configured as your default PDF viewer. Similarly, to view website materials and HTML formatted documentation, you must have Internet Explorer or Netscape installed and configured as your default web browser.

1.2.3 Python versions

Wing contains its own subset of Python 1.5.2 that is used to run the IDE itself (but should not be used for running your debug programs). The debugger, which runs in a seperate process, can run under Python 1.5.2, 2.0, or 2.1.

In most cases, Wing will work out of the box, will find your default python installation, and will use it for debugging. You can, however alter the version of Python that is used to debug your program by using Project Properties and per-file Debug Properties dialogs. See section 6.2 for details.

The interpreter that is used for debugging is also used to determine which version of the Python manual is displayed from the Help menu, and it affects which Python standard libraries are used for source code analysis. See section 5.6 for more information.

1.2.4 Linux Installation with RPM

Wing can be installed from an RPM package on RPM-based systems, such as RedHat and Mandrake. RPM packages for Wing are available from wingide.com. After downloading the package file, run rpm -i wingide-1.1b7-2.rpm as root or use your favorite RPM administration tool to install the RPM. The RPM places most files for Wing under the /usr/lib/wingide directory and creates links for the wing and wingdb commands in the /usr/bin directory.

RPM installation also creates a directory called floating-locks in /usr/lib/wingide. This is set up to be world writable by default. If you are worried about the security of this location, you may change its permissions or remove it entirely, as long as you don't plan a multi-user installation (described in section 1.7).

In the text that follows, the installation location of Wing is referred to as WINGHOME. If you installed from RPM, this will always be /usr/lib/wing.

1.2.5 Linux Installation from Tar Archive

Wing may also be installed from a tar archive. This can be used on systems that do not use RPM, or if you wish to install Wing into a directory other than /usr/lib/wingide. The tar archive is available from wingide.com. Unpacking this archive with tar -zxvf wingide-1.1b7-2.tar.gz will create a wing-1.1b7-2 directory that contains the wing-install.py script and a binary-package.tar file.

Running the wing-install.py script will configure Wing for use with individual licenses (multi-user installation is described in section 1.7). The install script will prompt for the location to install support files for Wing (WINGHOME), and the location in which to create symbolic links to wing and wingdb. These locations default to /usr/local/lib/wingide and /usr/local/bin, respectively. The install program must have read/write access to both of these directories, and all users running Wing must have read access to both.

In the text the follows, the installation location of Wing is referred to as WINGHOME. If you installed from tar, this will be the location you chose when you ran the installer.

1.2.6 Windows Installation

On Windows, Wing is installed by running the installer executable. The installer relies on the Microsoft installer engine, which will be installed automatically if it is not already on your system. Wing's files are installed by default in C:\Program Files\Wing IDE, but this location may be modified during installation. All users of Wing must have Create File and Write privileges to C:\Program Files\Wing IDE\profiles. This is where per-user preferences and other information is stored on Windows. Except for a shortcut in the Start menu heirarchy, all files are installed underC:\Program Files\Wing IDE.

In the text the follows, the installation location of Wing is referred to as WINGHOME. If you installed to the default location, this is C:\Program Files\Wing IDE.

1.3 Adding Wing to your Path (for Linux)

In many cases, the Wing executable will already be on the user path. If it is not, you may type in the full path to Wing, or add the location where Wing's executable was installed to your path. This location will be /usr/bin if the IDE was installed from RPM. When installed from tar file, it will be the value supplied to the wing-install.py script.

Setting the path may be done system-wide or individually. How this is done will differ according to your exact OS version, the shell you are running and, in some cases, the preferences of your system administrator. Typically, per-user setup is in ~/.profile, ~/.login, ~/.bashrc, ~/.cshrc, or equivalent shell configuration file, and system-wide setup is accomplished with /etc/profile, /etc/cshrc, or /etc/csh.login.

After installing or altering a user's path, you may need to open a new shell for that user or request that the shell rescan the disk for executables (for example, with rehash under tcsh).

If for some reason you cannot set the path, typing the full path to the wing executable, creating a small shell script containing the full path, or setting an alias will all work as alternatives.

1.4 Running the IDE

You are now ready to use Wing IDE!

On Windows, start Wing IDE from the Program group of the Start menu. To start it on Linux, just type wing (or the full path to the executable as described in the previous section).

The first time you run, Wing will create your personal settings directory, ~/.wingide on Linux or WINGHOME\profiles\[username] on Windows. If no user is logged in on Windows, "Default User" is used as the username. The personal settings directory is used to store your license, preferences, and other files used by Wing. If the directory cannot be created, Wing will exit.

Once the personal settings directory has been created, Wing will ask you to locate your license file. This is the file that was emailed to you when you signed up to try the demo, or purchased a permanent license. Once you locate the file, Wing will copy it into place in ~/.wingide/license.dat (on Linux) or WINGHOME\profiles\[username] on Windows. You will then be asked to accept the license terms.

At this time, Wing will also take the opportunity to ask you to specify a few major options, such as your preferred editor personality, print paper size (Linux only), and whether or not to auto-save project files. You may either select values or ask to always use the system defaults (as defined in WINGHOME/preferences). Once this is done, Wing will place a file called ~/.wingide/preferences (on Linux) or WINGHOME\profiles\[username] (on Windows), with contents according to your choices. This will include at most only a few of all the available preferences, and you can add to or alter these values at any later time. Please refer to WINGHOME/preferences and the rest of this manual for more information about all the supported options.

Whenever you run wing from the command line, you may specify a list of files to open. These can be arbitrary text files and a project file. For example, the following will open project file myproject.wpr and also the three source files mysource.py, README, and Makefile:

wing mysource.py README Makefile myproject.wpr
       

(on Windows, the executable is called wing.exe)

Wing determines file type by extension, so position of the project file name (if any) on the command line is not important.

1.5 Installing a Permanent License

The Wing IDE trial license is a temporary unlimited-user license that will expire one month from issue. If you have decided to purchase the product from the wingide.com website, you will receive your permanent license file, called license.dat, via email.

To install a new license, make sure that no copies of Wing are running on your old demo license (they will cease to function when the license file is changed). Then remove or rename the demo license ~/.wingide/license.dat (on Linux) or WINGHOME\profiles\[username]\license.dat (on Windows). Next, run Wing and follow instructions as it prompts you to locate your license file. The new file will be moved into place by Wing. If your trial license has already expired, you can skip the step of removing the old file because Wing will automatically prompt you for a new license.

You are now ready to use the new license.

1.6 Installing Extra Documentation

The Help menu in Wing IDE provides quick access to the online versions of the Wing IDE manual, the Python documentation collection, and some useful web resources.

The HTML and PDF A4 and US Letter versions of the Wing manual are shipped by default with Wing's binary distribution. Additional manual formats are available from http://wingide.com/support/manual.

If you are using Linux, the Python manual is not included in most installations, so you may also wish to download and install local copies of these pages. Place the top-level of the HTML formatted Python manual (where index.html is found) into WINGHOME/python-manual/#.# in your Wing IDE installation. Substitute for #.# the major and minor version of the corresponding Python interpreter (for example, 1.5 or 2.0). Once this is done, Wing will use the local disk copy rather than going to the web when the Python Manual item is selected from the Help menu.


1.7 Multi-user Installations (Linux only)

A multi-user installation requires that you have the ability to share a common disk area among all the machines that will participate in the installation. This is usually done via NFS under Linux, although other file sharing techniques (such as Samba) will also work.

The primary difference between multi-user installation and single-user installation is the location and nature of the license file. In single-user installations, licenses are in ~/.wingide/license.dat and license lock files are placed in /var/tmp. In multi-user installations, licenses and license lock files are both in WINGHOME/floating-locks.

There are two approaches to setting up a multi-user installation:

If you have installed from RPM, the floating-locks directory should already exist and be world-writable on each installation, and the IDE should be configured to use it. You only need to alter the installation if you want to change the permissions on the lock file directory or if you want to replace it with a symbolic link, as described above.

If you installed from tar file, you need to perform the installation in a way that indicates that you want it to work in multi-user mode. This is done by running wing-install.py --multi-user. At the end of the installation process, this will ask for the name of the directory that should contain license lock files and will create the directory if it does not exist. The script will also ask for the name of the group that all users of the floating license must belong to. Use <everyone> to specify that all users can use the floating license. Any group specified must exist prior to running the install script.

In either case, once installation is complete, you must copy the multi-user license file that you have purchased into WINGHOME/floating-locks and make sure it is readable by all users of the installation.


   If copies of Wing crash or are terminated from outside, the license lock files located in /var/tmp (or in WINGHOME/floating-locks in multi-user installations) may be left in place, consuming one user license each. To fix this, remove those files for which no Wing instance is running. The file name combines the license number, host name, and process ID of Wing so it is possible to determine whether a file is a lost file or an active file:

BD12-A63A-690C-A517-pangolin-982

Be careful not to remove an active license lock file, as the Wing instance that is using it will cease to function until it is restarted.



1.8 Source Installation

All non-evaluation licenses allow the source code for Wing to be obtained from wingide.com. The source is available either as an RPM package or as a tar archive. You should use the RPM if you used the RPM to install the binary, and the tar file if you used the tar file to install the binary.

1.8.1 For Linux

The RPM package installs the source into /usr/lib/wingide and is installed by running rpm -i wingide-source-1.1b7-2.rpm as root or using your favorite RPM administration tool. The tar archive contains a source-package.tar file and a copy of the wing-install.py script.

To install from the tar file, obtain the wingide-source-1.1b7-2.tar.gz tar archive as available from wingide.com. Unpacking this archive with tar -zxvf wingide-source-1.1b7-2.tar.gz will create a wing-source-1.1b7-2 directory that contains the wing-install.py script and a source-package.tar file. Running the wing-install.py script will ask for the location of your binary installation and then will overlay the source files on top of it.

If you are planning to modify the Wing IDE source, it is strongly recommended that you either install the source as a non-root user from the tar archive, or copy it from /usr/lib/wingide as a non-root user. Otherwise only root will be able to modify the source.

See the file src/README.LINUX for more information on getting started developing on Linux.

1.8.2 For Windows

To install source on Windows, obtain the wingide-source-1.1b7-2.tar.gz tar archive as available from wingide.com. Copy the contents of your Wing IDE binary installation to your development location and then unpack the file source-package.tar (found in the source distribution) manually into your development location.

Setting up for development on Windows is complicated and requires a number of additional tools and downloads. See the file src/README.WIN32 for details on getting started.

1.9 Removing an Installation

On Windows, use the Add/Remove Programs control panel, select Wing IDE and remove it.

To remove an RPM installation on Linux, type rpm -e wingide. If you have also installed the source distribution or other support RPMs, these must be removed also. Source must be removed before the binary rpm or at the same time as the binary rpm. Use the rpm -e wingide wingide-source command to remove both rpm's at the same time.

To remove a tar archive installation on Linux, invoke the wing-uninstall script in WINGHOME. This will automatically remove all binary and source files in the installation that appear not to have been changed since installation, including source files. It will ask whether it should remove any files that appear to be changed.


next up previous contents
Next: 2. Customization Up: Wing IDE Reference Manual Previous: Contents   Contents


Stephan R.A. Deibel
2001-09-17