Wikipedia:WikiProject Tropical cyclones/Tracks/Cygwin

This help page is a how-to guide.

It explains concepts or processes used by the Wikipedia community. It is not one of Wikipedia's policies or guidelines, and may reflect varying levels of consensus.

This page documents usage of the WikiProject Tropical cyclones track maker using Cygwin on a Windows computer. This guide is intended for those who are relatively inexperienced with the command line but still want to create their own track maps.

Installing Cygwin

Cygwin can be downloaded from https://cygwin.com/install.html. You are supposed to install setup-x86_64.exe for 64-bit Windows installations, and setup-x86.exe otherwise. To check your system architecture, press ⊞ Win+Pause Break to open your system information panel. Your operating system architecture will be under the "System type" field.

When running the installer, proceed with the following options (you may deviate if you know what you're doing):

Select "Install from Internet" as the download source
Select a place to install Cygwin. This will normally be found at C:\cygwin64. Do remember where you install it, since you'll have to return to that folder later.
The local package directory is simply a place to temporarily hold installation files. You can use your Downloads folder for this, but if you prefer to place the temporary files somewhere else, you may change the location.
If you are accessing the server under a proxy, you may input your proxy information here. Otherwise, you can just stick to "Use System Proxy Settings".

Cygwin will proceed to download a list of mirrors. The list can be found online here. It's best to select a mirror in your country, or a country closest to your location. Once you've decided on a mirror to use, find the link of that mirror on the Cygwin installation screen. Cygwin will then download a list of packages that you can install.

From the new window, you should now search for and download the prerequisites found on the main guide. Switch the view from "Pending" to "Full" with the dropdown on the top-right to see all installable packages. In total, you should install have installed the latest version of the following packages:

autoconf (?)
automake (?)
libcairo-devel (?)
gcc-core (?)
gettext (?)
git (?)
make (?)
perl (?)
pkg-config (?)
wget (optional) (?)

Cygwin should automatically install all the dependencies of those packages. If you forgot to install a package, you can just run the Cygwin installer again and select the packages to add. If at any moment you choose to remove Cygwin, you can uninstall it from the Programs and Features menu of the Control Panel. You can also delete your Cygwin installation folder.

Installing the track map generator

Once you've successfully installed Cygwin and the required packages, it's time to clone the track map generator and compile it for use. This section requires knowledge of basic command line commands. A short summary of the commands you might need is available below for the uninformed.

Extended content

cd is used to change the current directory (i.e. folder). The current directory is usually shown in yellow in Cygwin, above the line with the $. You can use .. to refer to the directory above (thus, cd .. will move you to the directory outside the current). . refers to the current directory. ./autogen.sh, for example, will look for an "autogen.sh" file in the current directory.
ls allows you to see the files and folders of the current directory. By default, this outputs a columned set of files and folders, which can be hard to interpret. Running ls --color=auto will color folders blue and standard files white. This can help you get your bearings in case you get confused on which directory you're in.

To open Cygwin, select "Cygwin Terminal" in your Start menu, or navigate to your Cygwin installation folder and run the Cygwin.bat file. To run commands, type the command in the opened window, and press the ↵ Enter button.

Downloading

Begin by cloning the repository into a directory of your choice. The default directory (~) is located in your user folder (C:\Users\<username>). You may choose to navigate to the Desktop (using cd Desktop) or some other folder. From here, run the following command to get the latest copy of the track map generator.

git clone https://github.com/titoxd/wptc-track.git

This will create a folder named wptc-track inside the current directory. Most of our work will be in the tracks folder of that folder. Instead of individually running cd wptc-track and cd tracks, you may run cd wptc-track/tracks instead. You'll be able to compile the track map generator here.

Compiling

To automatically configure the generator, you'll need to run autogen.sh. To do this, just run the following command:

./autogen.sh

If you experience an error while configuring, refer to the § Troubleshooting section. If you didn't, congratulations! It's now time to compile the track maker. To compile, just run make using the following command:

make

This compiles all source files into object files, and then links them into one file: track.exe. If you experience an error while compiling, refer to the § Troubleshooting section. There should now be a track.exe file within the tracks folder. You can now use this to generate track files. You can test it out using ./track --help to see if it works or not.

Running make without any additional options will simply compile the track map generator. It will be inaccessible unless you are in the tracks folder. To be able to run ./track everywhere (and also allow you to run it without the preceding ./), you can instead run make install. By doing this though, you need to set the input file using the --input argument, as it will no longer be able to find the North Atlantic basin data (since it is being run from outside its normal directory).

Running

The track map generator is run exactly as it is run in the main guide. You can refer to that for information on how to run the generator.

Troubleshooting

`autogen.sh` syntax errors

Syntax errors with autogen.sh, specifically the following, are indications that you are using CRLF (Windows) line endings instead of LF (Unix) line endings:

./autogen.sh: line 5: $'\r': command not found
./autogen.sh: line 7: $'\r': command not found
./autogen.sh: line 22: syntax error near unexpected token `$'\r''
'/autogen.sh: line 22: `version_check()

Use any tool available to you in order to convert the line endings from CRLF to LF. If you wish, you may install the Cygwin package dos2unix to convert the line endings. After installing it, run dos2unix autogen.sh in the tracks/ folder.

Some prerequisites not found

Ensure that you installed all the required packages and dependencies. The list in the § Installing Cygwin section should contain all required packages. Their dependencies should also be installed with them. Do not attempt to remove the dependency of one of those packages, or else the required package will not work.

Package 'cairo' not found

Ensure that the libcairo-devel package has been installed. If it is installed, but you're still experiencing this error, install the libcairo2 package as well.

File permissions

If make fails with a permissions error, ensure that you are using the gcc that you installed with Cygwin. In case you already had gcc installed somewhere else on your computer and it can be found in your PATH, you can try clearing out your path by setting it to the bare minimum with the following command:

export PATH=/usr/local/bin:/usr/bin:/bin:/cygdrive/c/Windows/system32:/cygdrive/c/Windows:/cygdrive/c/Windows/System32/Wbem

Attempt to run autogen.sh and make once this has been done.

You can also try to run both commands under administrator privileges, although this might not work. You can use the following command to get access to an elevated (i.e. has administrator privileges) shell:

cygstart --action=runas sh

After running the command, you will be asked for administrator privileges. From here, you can run autogen.sh and make. The file permission errors should disappear.

Code execution cannot proceed because cygcairo-2.dll was not found

This issue appears when attempting to run the track.exe file with a normal command interpreter. You need to run the compiled track.exe file using Cygwin, not the built-in Windows Command Prompt.