Language

The Free and Open Productivity Suite
Released: Apache OpenOffice 4.1.15





website.openoffice.org HowTos


Installing and using CVS under Windows

Credits: this HowTo is the result of the combined efforts of the website.openoffice.org mailing-list members. This file is on the OpenOffice.org server because of their collaboration. We hope that this summary, and any improved or rewritten version in the future will help others to enjoy CVS-ing and online HTML collaboration in as pleasurable and effective a way as possible. It is not difficult at all. It is, in fact, extremely easy, easier than ftp-ing. So if you can ftp, you will certainly be able to CVS using the combined tools of Cygwin and TortoiseCVS.

Miljenko Williams

Improvements to the original document made by Johannes Czerwinski. Corrections and comments made by Gianluca Turconi, 10th September 2002.

related e-mail thread | email comments etc. to dev@website.openoffice.org




Downloading and installing Cygwin | top

Make sure you are connected to the Internet.

Go to www.cygwin.com and download the setup.exe executable to your computer, the icon of which you will see on the homepage somewhere. Remember the following:

  • this file simply administers the process of choosing which files to download to your computer, the download process itself (if you are disconnected from the Internet whilst you are downloading from a server which supports the function, you will be able to carry on from where you left off when you reconnect by simply clicking on setup again) and unzipping and installing once everything has been downloaded. When you download the Cygwin setup.exe, you will not yet have downloaded the Cygwin program. The Cygwin setup.exe simply makes it possible for you to download the program files you need in order to install Cygwin on your hard drive
  • if you are disconnected whilst downloading the Cygwin files, when you reconnect and restart the download process, you may think it is starting from scratch as the setup.exe file always reloads a file called setup.ini from the download server. Do not think you are starting from scratch. The setup.ini is always re-downloaded from the server when you reconnect from a broken connection, but the download process will pick up from where it left off (or from the beginning of the last file incompletely downloaded), once the setup.ini has been re-downloaded
  • please do not try and use WinZip or any other ZIP program to unzip and install Cygwin at any point. The Cygwin setup.exe file will do it for you and will do it correctly
  • if you ever need to uninstall any or all of the files, you should use the setup.exe to do so. Click here for more information on how to uninstall

Choose A Download Source: once you have downloaded the Cygwin setup.exe file, click on the setup.exe icon and click the Next button. You will be asked to choose between Install from Internet, Download from Internet or Install from Local Directory. Choose Download from Internet and click the Next button.

Select Local Package Directory: you will now be asked to define the local package directory (where you want the downloaded files to be stored to on your hard drive – not where the program folder or files will eventually be placed). This can be any folder where you normally download files to from the Internet. We suggest you create a folder called Cygwin Download Files to download the files to. Click on the Next button

Select Your Internet Connection: select Direct Connection (and make sure you are already connected to the Internet) and then click on the Next button

Choose a Download Site: we suggest you choose http://mirrors.sunsite.dk, as this site supports re-downloading from where you left off if you are disconnected from the Internet whilst still downloading files. Other mirrors and servers may also offer this facility. Remember the following:

  • not all mirrors appear to update the setup.ini regularly. The setup.ini may therefore change from server to server. It's best to choose a server, check it works for you, and continue the download process through to the end, instead of changing servers halfway and running the risk of starting up again with a different setup.ini and the problems that may (or may not) be generated for you

Select packages to download: you must now ensure the following packages (program files) are selected for download. Remember the following:

  • if you have to select certain packages manually, because they are not selected by default, and you are then disconnected from the Internet whilst downloading the packages, when you reconnect to the server and the setup.ini (the download instructions which tell the server what packages) is re-loaded, it will be re-loaded with the default selections only. You must therefore always reselect manually any packages you had to select manually first time round. If you do not do so, they will not be downloaded and Cygwin will not necessarily work for you

First click the View button. This will open up the list of packages which can be downloaded and show you which of them are selected by default. In addition to the packages which are selected by default, you have to select the following packages manually:

  • - cvs (Category: Devel)
  • - openssh (Category: Net)
  • - openssl (Category: Libs)
  • - patch (Category: Utils)

Now click the Next button and wait for the files you have selected to be downloaded.

Once the files have been downloaded, installation is very simple. Click again on the setup.exe as before, and when you get to the section Choose a Download Source, select Install from Local Directory, the directory being the directory you downloaded the program files to from the Internet. Click on Next.

Select Root Install Directory: the default directory is C:\cygwin. We suggest you do not modify this default. Leave all other selections as default and click on Next.

Select Local Package Directory: the default directory will be the directory you downloaded the program files to from the Internet. We suggest you do not modify this default. Click on Next.

Select packages to install/keep/reinstall/uninstall: make sure the default packages as listed above are all checked to be installed if this is the first installation. If a package shows Keep, this means the package is already installed. Remember the following:

  • if you ever need to uninstall any or all of the packages, instead of checking the packages to Keep or Reinstall, select Uninstall at this point in the process

Click on Next. The packages will now be installed.


Generating your public and private keys | top

Click on the Cygwin icon which you should have on your Desktop. This will open a black window. Type the following line into the black window:

ssh-keygen -d

This commands the program to generate an SSH2 key (the -d extension specifies a DSA/SSH2 key which is the type that OpenOffice.org needs). Depending on the speed of your processor, it could take anywhere from several seconds to several minutes. When finished, it will prompt you for a file in which to save the key. You should press the Enter key without typing anything else in. Although the prompt appears to be a filepath without a filename, it does actually include the filename too. Don't add anything else to this filepath and name - if you do you will then have problems later on which you will only be able to solve if you understand how to use Unix directories.

You will then be asked to enter a passphrase. It is strongly recommended that you enter one, and that it be fairly good. (This means: try to avoid using real words, change the case, incorporate numbers, symbols, or some other combination.)

Whilst you are keying in your passphrase, you will not see any characters being typed up onto the black window, nor will a cursor move. You are nevertheless registering the passphrase as you type. You will be asked to enter this passphrase twice. Make sure you make careful note of it: you will be asked for it every time you log in to the OpenOffice.org SSH2 server, which you will have to connect to using this public key.

Once you have entered the passphrase twice, you will then be told that the "identification" has been saved in the default file you stipulated above, and that the "public key" has been saved in a file bearing that same name but with a .pub suffix. The .pub signifies that it is the public key. It is this file you should then send to OpenOffice.org. You will find it in the following folder (as long as you have used default values throughout the installation):

C:\cygwin\home\Standard\.ssh

In order to be able to use this public key, you should either send it via the OpenOffice.org IssueZilla bug-reporting system, if you know how to do this, logging in with your OpenOffice.org website login name and password (not the passphrase you have used to generate the public key), creating an issue which you can call My Public Key or something similar, and then attaching the public key to the issue.

You may however prefer to ask your project leader to help you with the procedure.

In any case, once this public key has been placed on the OpenOffice.org server, and you have been told it has been placed there (it is not an automatic process and you may have to wait a few days), you will be able to continue with the process of CVS-ing under OpenOffice.org.

Remember that this public key will be used in conjunction with your OpenOffice.org website login name, and that although you need the passphrase associated with the public key to tunnel, your website login name and associated password are needed for you to be able to use the tunnel in order to CVS on the OpenOffice.org site. That is to say:

  • you need your public key to be physically present on the OpenOffice.org server in order to create a tunnel
  • your need to have an OpenOffice.org website login name and login password to be able to CVS on an OpenOffice.org project, using the tunnel you have created

Creating a tunnel and minimising the window | top

First, click on the Cygwin icon on your Desktop. The black window will open again. At the prompt, enter the following phrase:

ssh -2 -x -L 2401:localhost:2401 tunnel@openoffice.org

If you have problems typing in the "@" sign, you may have a key on your keyboard which is called Alt Gr, or Alt plus something else: press it along with the key where the "@" sign appears.

The server will ask you for your passphrase. Enter it. If this is your first time, the server will send you a message along these lines:

Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)?

Enter:

Yes

(You can't just enter "y"; you have to spell it out fully.)

The server will then respond with:

Host "openoffice.org" added to the list of known hosts

The screen does not show a prompt. That's how it should be. The tunnel has been established. You are now ready to begin using CVS. You can, at this point, minimize the black window, but do not close it by clicking on the X in the top right-hand corner. If you close it, you will be closing the tunnel you have just created.


Opening a new window in Cygwin, logging on to a project repository (the folder where the HTML files of a project are stored), and checking out a project repository (downloading the files from the online repository to your hard drive for the first time) | top

Once you have minimised the existing Cygwin window which you have used to create a tunnel, you should now click on the Cygwin icon again to open a new window.

At the prompt, type in the following command:

cvs -d:pserver:{my openoffice.org website login name}@localhost:/cvs login

For example, if your OpenOffice.org login name is "walter", you will type in the following command:

cvs -d:pserver:walter@localhost:/cvs login

You will now be asked for your CVS password, which is the password associated with your OpenOffice.org website login name, not the passphrase you have used in conjunction with the public key you generated to create a tunnel.

Once you have logged in to the CVS repository successfully, you can type in the following command which will download onto your hard drive the current content of the project you are going to work on:

cvs -z3 -d:pserver:{your openoffice.org login name}@localhost:/cvs checkout {the name of your project}

For example, if your OpenOffice.org login name is "walter" and the project you are going to work in is the Spanish lang project, you will type in the following command:

cvs -z3 -d:pserver:walter@localhost:/cvs checkout es

Once you have successfully downloaded the content of your project (you will find it within the Cygwin folder: C:\cygwin\home\Standard if you have used default values or within the current user if you have defined your own values), you are ready to continue with the installation process.

At the prompt, type in Control C and then exit - this will logout from the CVS server and close the window. If you close the window this way, instead of by clicking on the X in the top right-hand corner, the next time you open the window CVS, you will be able to use the up/down arrows to flick through the commands you have used to create the tunnel etc. and you will not need to type them laboriously in letter by letter.

Maximise the black window you had created to tunnel with and press Control C at the prompt. This will close the tunnel, but not the window. Then type in exit and this will close the window. If you close the window this way, instead of by clicking on the X in the top right-hand corner, the next time you open the window, you will be able to use the up/down arrows to flick through the commands you have used to create the tunnel etc. and you will not need to type them laboriously in letter by letter.


Downloading and installing Tortoise CVS | top

Assuming you are connected to the Internet, go the following web:

http://www.tortoisecvs.org/download.shtml,
or simply http://www.tortoisecvs.org (and then look for the Download link)

Choose the most recent stable version of TortoiseCVS available and download it to your hard drive.

Install the program, using the default values in all circumstances.

Once you have installed TortoiseCVS, you will see that when you right-click on any folder under Windows Explorer, you will see a series of commands have been added to the normal ones on this menu. You are now ready to upload modified files to your project's OpenOffice.org repository. The meaning of the four most important commands is explained in the following section.

NOTE 1: If Cygwin is handling text files in Unix format, you should uncheck the "Check not Unix sandbox" in the Quirky tabs of TortoiseCVS preferences. If you do not do so, an annoying dialogue box will pop up complaining about "an attempt to checkout Unix Sandbox on Windows machines"; TortoiseCVS may then crash.

NOTE 2: With a standard Cygwin and TortoiseCVS installation, you may have to select the Cygwin CVS binary in order to be able to use TortoiseCVS under the procedures described in this HowTo.


Updating (downloading files from a project repository to your hard drive which have been modified by other developers), committing (uploading files to a project repository from your hard drive which you modified), adding new files (one new folder or one new HTML file which didn't previously exist in the repository), and adding new files recursively (add a folder or several folders and/or several HTML files which didn't previously exist in the repository) | top

There are four basic commands which you will need to understand in order to modify files within your project and upload them to the project site.

Before you do so, you should understand the meaning of the following:

  • updating - this means downloading files from a project repository on the OpenOffice.org server to your hard drive which have been modified by other developers. This is not the same as when you "checked out" - "checking out" is creating a copy of the repository on your hard drive for the very first time
  • committing - this means uploading files to a project repository on the OpenOffice.org server which you have modified
  • adding - this means creating a new filename on the project repository, after first having created the file itself on your hard drive. This file will only ever exist on the project repository if you use both the "add" command first (adding means that you are registering the new filename on the repository), and then the "commit" command second (making the addition a reality by sending the content associated with that filename)
  • adding recursively - this means that instead of first "adding" a new folder name and then "committing" it, and then "adding" each file within that new folder one by one and "committing" them by one by one, you can simply choose to "add recursively" (register both the new folder name and/or multiple filenames together) and then "commit" the whole folder (sending all the content associated with all the new filenames you have registered together)

In order to do all of this, you only need to remember the following:

  1. Create a tunnel first, using the procedure already described above. Don't forget to minimise the black window
  2. Use Windows Explorer to find the folder where your project repository has been stored on your own hard drive. If your project is the Spanish lang project and you have used default values throughout the whole installation of Cygwin, you will find your project files in the following folder:

    C:\cygwin\home\Standard\es\www

In order to update, commit, add or add recursively, all you need to do is select the folder which contains files you need to work on, click on your right-hand mouse button, and select the command you need to use. The process will then be carried out automatically.

We hope you enjoy your CVS-ing with OpenOffice.org for a long time to come.












Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache, OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. The Apache feather logo is a trademark of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.