Hi all, - way too many changes to list them OK, I'm just joking ;-) Here is the list of major changes that I can still find out about: Users Guide: - new, much more detailed and easier "step-by-step" layout - better intro - add Glossary (glossary.sgml) - MUCH better Getting Wine chapter - much better Wine configuration chapter - better Wine drive layer configuration section - explain wineserver cmdline options - rearranged tons of things into a less messy state - tons of janitorial fixes - much much more that I don't really care about right now Developers Guide: - add complete CVS chapter (cvs.sgml) This documentation patch also incorporates several other patches previously submitted by some people. Note that this patch might appear a bit unfinished at some corners (especially the installation path throughout the document might be twisted or broken in some cases). However, I really can't stand having it in my queue even longer, so I had to submit it now. If there is anything broken, then please report to me for inclusion in a later patch. Note that about 90% of this work could have been done by *anyone*, but nooo, a Wine developer has to take care of enduser work, again... Andreas Mohr -- Help prevent Information Technology Fascism! - before it's too late... http://www.againsttcpa.com
<chapter id="cvs"> <title>Using CVS</title> <!-- this part is sort of duplicated in the Wine User Guide's getting.sgml file (as a short intro to CVS). Please don't forget to update both! --> <sect1> <title>What is CVS?</title> <para> <ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent Versions System) is the leading source code control system in the freeware community. It manages source code of projects, keeps a history of changes to the source files and improves conflict management when two or more developers work on the same code part. Another major benefit of CVS is that it's very easy to update a project to the latest version. CVS features flexible branching, intelligent merging, high quality <ulink url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">documentation</ulink> and client/server access with a wide choice of <ulink url="http://www.loria.fr/cgi-bin/molli/wilma.cgi/rel">clients</ulink>. </para> <para> Current Wine sources are available via anonymous client/server CVS. You will need CVS 1.9 or above. If you are coming from behind a firewall, you will either need a hole in the firewall for the CVS port (2401) or use <ulink url="http://www.cyclic.com/cvs/d ev-net.html">SOCKS</ulink>. </para> </sect1> <sect1> <title>CVS installation check</title> <para> First you need to make sure that you have <command>cvs</command> installed. To check whether this is the case, please run: </para> <screen> <prompt>$ </><userinput>cvs</> </screen> <para> If this was successful, then you should have gotten a nice CVS "Usage" help output. Otherwise (e.g. an error "cvs: command not found") you still need to install a CVS package for your particular operating system, similar to the instructions given in the Wine User Guide chapters for getting and installing a Wine package on various systems. </para> </sect1> <sect1> <title>Configuring Wine-specific CVS settings</title> <para> First, you should do a </para> <screen> <prompt>$ </><userinput>touch ~/.cvspass</> </screen> <para> to create or update the file <filename>.cvspass</filename> in your home directory, since CVS needs this file (for password and login management) and will complain loudly if it doesn't exist. </para> <para> Second, we need to create the file <filename>.cvsrc</filename> in your home directory containing the CVS configuration settings needed for a valid Wine CVS setup (use CVS compression, properly update file and directory information, ...). The content of this file should look like the following: <programlisting> cvs -z 3 update -PAd diff -u checkout -P </programlisting> Create the file with an editor of your choice, either by running <screen> <prompt>$ </><userinput><editor> ~/.cvsrc</> </screen> , where <editor> is the editor you want to use (e.g. <command>joe</command>, <command>ae</command>, <command>vi</command>), or by creating the file <filename>.cvsrc</filename> in your home directory with your favourite graphical editor like nedit, kedit, gedit or others. </para> <para> <command>-z</command> sets the compression level (Levels higher than 3 will probably not result in faster downloading unless you have a fast machine and a slow network connection). <command>-Pd</command> will delete empty directories and create newly added ones. <command>-A</command> will reset any previous tag in order to get the latest version in the tree. <command>-u</command> will create the easiest to read patches. Please do not submit patches with <command>diff -w</command>. </para> </sect1> <sect1> <title>Downloading the Wine CVS tree</title> <para> Once CVS is installed and the Wine specific CVS configuration is done, you can now do a login on our CVS server and checkout (download) the Wine source code. First, let's do the server login: </para> <screen> <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.com:/home/wine login</> </screen> <para> If <command>cvs</command> successfully connects to the CVS server, then you will get a "CVS password:" prompt. Simply enter "cvs" as the password (the password is <emphasis>case sensitive</emphasis>: no capital letters!). If you want to use one of the mirror servers for Wine CVS download, please refer to the section <link linkend="cvs-mirrors">Wine CVS mirror servers</link>. </para> <para> After login, we are able to download the Wine source code tree. Please make sure that you are in the directory that you want to have the Wine source code in (the Wine source code will use the subdirectory <filename>wine/</filename> in this directory, since the subdirectory is named after the CVS module that we want to check out). We assume that your current directory might be your user's home directory. To download the Wine tree into the subdirectory <filename>wine/</filename>, run: </para> <screen> <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.com:/home/wine checkout wine</> </screen> <para> Downloading the CVS tree might take a while (some minutes to few hours), depending on your connection speed. Once the download is finished, you should keep a note of which directory the newly downloaded <filename>wine/</filename> directory is in, by running <command>pwd</command> (Print Working Directory): </para> <screen> <prompt>$ </><userinput>pwd</> </screen> <para> Later, you will be able to change to this directory by running: </para> <screen> <prompt>$ </><userinput>cd <replaceable><some_dir></></> </screen> <para> , where <some_dir> is the directory that <command>pwd</command> gave you. By running </para> <screen> <prompt>$ </><userinput>cd wine</> </screen> <para> , you can now change to the directory of the Wine CVS tree you just downloaded. </para> </sect1> <sect1 id="cvs-mirrors"> <title>Wine CVS mirror servers</title> <para> Wine's CVS tree is mirrored at several places arround the world to make sure that the source is easily accessible. Note that not all servers have all repositories available, but all have at least the Wine source. </para> <para> CVS access is granted through CVS' "pserver" authentication. You should set your <command>CVSROOT</command> environment variable to point to one of the servers using this format: </para> <screen> CVSROOT=:pserver:<Username>@<CVS Server>:<Server root> </screen> <para> Alternatively, you can use the -d parameter of <command>cvs</command> instead. Substitude the applicable fields from the table below. </para> <para> Just do a traceroute and a ping on all servers below to find out which are closest to you. </para> <para> <table><title>Wine CVS servers</title> <tgroup cols=3 align="center"> <thead> <row> <entry>CVS Server</entry> <entry>Username</entry> <entry>Password</entry> </row> </thead> <tbody> <row> <entry>cvs.winehq.com; Minnesota, USA (CodeWeavers)</entry> <entry>cvs</entry> <entry>cvs</entry> </row> </tbody> </tgroup> </table> </para> </sect1> <sect1> <title>Other modules available via CVS from WineHQ</title> <para> The WineHQ CVS server makes a couple of other things available as well. To get these, log in anonymously as above and do: </para> <screen> <prompt>$ </><userinput>cvs co <replaceable><modulename></></> </screen> <para> where <modulename> is one of: </para> <itemizedlist> <listitem> <para> <emphasis>Winehq_com</emphasis> -- source for the WineHQ web site </para> </listitem> <listitem> <para> <emphasis>c2man</emphasis> -- automatic documentation system, specially modified for Wine </para> </listitem> </itemizedlist> </sect1> <sect1> <title>Converting a Wine FTP download to a CVS tree</title> <para> Getting the entire Wine source tree via CVS is pretty slow, especially compared to getting Wine from an FTP mirror near you. It's possible to convert a Wine tarball to a CVS sandbox, just like you would get by checking out the entire source via CVS. Here's how to do it: </para> <itemizedlist> <listitem> <para> Get the latest Wine snapshot: Wine-<replaceable>YYMMDD</replaceable>.tar.gz </para> </listitem> <listitem> <para> Get wine-cvsdirs-<replaceable>YYMMDD</replaceable>.tar.gz from <ulink url="ftp://ftp.winehq.com/pub/wine/">ftp://ftp.winehq.com/pub/wine</ulink> </para> <para> Use an FTP client rather than a web browser, and be sure to turn off passive mode, otherwise the fetch will hang. </para> <para> e.g.: </para> <screen> ftp ftp.winehq.com cd pub/wine passive off ls </screen> </listitem> <listitem> <para> Untar them on top of each other: </para> <screen> tar xzf Wine-<replaceable>YYYYMMDD</replaceable>.tar.gz mv wine-<replaceable>YYYYMMDD</replaceable> wine tar xzf wine-cvsdirs-<replaceable>YYYYMMDD</replaceable>.tar.gz </screen> </listitem> <listitem> <para> Update from main tree: login as above, then do </para> <screen> cd wine cvs update -PAd </screen> </listitem> </itemizedlist> <para> You will now be completely up to date. </para> </sect1> <sect1> <title>WineHQ cvsweb access</title> <para> Direct access to the complete CVS tree is also possible, using Bill Fenner's <ulink url="http://www.freebsd.org/~fenner/cvsweb/">cvsweb</ulink> package: <itemizedlist> <listitem> <para> <ulink url="http://cvs.winehq.com/cvsweb">cvs.winehq.com/cvsweb</ulink>, on the primary CVS repository </para> </listitem> </itemizedlist> </para> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "") End: -->
<glossary> <title>Glossary</title> <!-- EXAMPLE: <glossdiv> <title>test</title> <glossentry sortas="rme"> <glossterm id="bad_mistake">Very Stupid Mistake</glossterm> <glosssee>things_to_avoid</glosssee> <acronym>VSM</acronym> <abbrev>Doh!</abbrev> <glossseealso otherterm="accident"> <glossdef> <para>Something you should try to avoid at all costs.</para> </glossdef> </glossentry> </glossdiv> --> <glossdiv> <title></title> <glossentry> <glossterm>Binary</glossterm> <glossdef> <para> A file which is in machine executable, compiled form: hex data (as opposed to a source code file). </para> </glossdef> </glossentry> <glossentry> <glossterm>CVS</glossterm> <glossdef> <para> Concurrent Versions System, a software package to manage software development done by several people. See the CVS chapter in the Wine Developers Guide for detailed usage information. </glossdef> </glossentry> <glossentry> <glossterm>Distribution</glossterm> <glossdef> <para> A distribution is usually the way in which some "vendor" ships operating system CDs (usually mentioned in the context of Linux). A Linux environment can be shipped in lots of different configurations: e.g. distributions could be built to be suitable for games, scientific applications, server operation, desktop systems, etc. </para> </glossdef> </glossentry> <glossentry> <glossterm>DLL</glossterm> <glossdef> <para> A DLL (Dynamic Link Library) is a file that can be loaded and executed by programs dynamically. Basically it's an external code repository for programs. Since usually several different programs reuse the same DLL instead of having that code in their own file, this dramatically reduces required storage space. A synonym for a DLL would be library. </para> </glossdef> </glossentry> <glossentry> <glossterm>Editor</glossterm> <glossdef> <para> An editor is usually a program to create or modify text files. There are various graphical and text mode editors available on Linux. </para> <para> Examples of graphical editors are: nedit, gedit, kedit, xemacs, gxedit. </para> <para> Examples of text mode editors are: joe, ae, emacs, vim, vi. In a <glossterm>terminal</glossterm>, simply run them via: </para> <screen> <prompt>$ </><userinput><replaceable>editorname</replaceable> <replaceable>filename</replaceable></> </screen> </glossdef> </glossentry> <glossentry> <glossterm>Environment variable</glossterm> <glossdef> <para> Environment variables are text definitions used in a <glossterm>Shell</glossterm> to store important system settings. In a <command>bash</command> shell (the most commonly used one in Linux), you can view all environment variables by executing: </para> <screen> <userinput>set</userinput> </screen> <para> If you want to change an environment variable, you could run: </para> <screen> <userinput>export <replaceable>MYVARIABLE</>=<replaceable>mycontent</></userinput> </screen> <para> For deleting an environment variable, use: </para> <screen> <userinput>unset <replaceable>MYVARIABLE</></userinput> </screen> </glossdef> </glossentry> <glossentry> <glossterm>Package</glossterm> <glossdef> <para> A package is a compressed file in a <glossterm>distribution</glossterm> specific format. It contains the files for a particular program you want to install. Packages are usually installed via the <command>dpkg</command> or <command>rpm</command> package managers. </para> </glossdef> </glossentry> <glossentry> <glossterm>root</glossterm> <glossdef> <para> root is the account name of the system administrator. In order to run programs as root, simply open a <glossterm>Terminal</glossterm> window, then run: </para> <screen> <prompt>$ </><userinput>su -</> </screen> <para> This will prompt you for the password of the root user of your system, and after that you will be able to system administration tasks that require special root privileges. The root account is indicated by the </para> <screen> <prompt># </> </screen> <para> prompt, whereas '$' indicates a normal user account. </para> </glossdef> </glossentry> <glossentry> <glossterm>Shell</glossterm> <glossdef> <para> A shell is a tool to enable users to interact with the system. Usually shells are text based and command line oriented. Examples of popular shells include <command>bash</command>, <command>tcsh</command> and <command>ksh</command>. Wine assumes that for Wine installation tasks, you use <command>bash</command>, since this is the most popular shell on Linux. Shells are usually run in a <glossterm>Terminal</glossterm> window. </para> <!-- <glossseealso otherterm="Terminal"> --> </glossdef> </glossentry> <glossentry> <glossterm>Source code</glossterm> <glossdef> <para> Source code is the code that a program consists of before the program is being compiled, i.e. it's the original building instructions of a program that tell a compiler what the program should look like once it's been compiled to a <glossterm>Binary</glossterm>. </para> </glossdef> </glossentry> <glossentry> <glossterm>Terminal</glossterm> <glossdef> <para> A terminal window is usually a graphical window that one uses to execute a <command>Shell</command>. If Wine asks you to open a terminal, then you usually need to click on an icon on your desktop that shows a big black window (or, in other cases, an icon displaying a maritime shell). Wine assumes you're using the <command>bash</command> shell in a terminal window, so if your terminal happens to use a different shell program, simply type: </para> <screen> <userinput>bash</> </screen> <para> in the terminal window. </para> </glossdef> </glossentry> </glossary>
Attachment:
docu.diff.bz2
Description: BZip2 compressed data