diff options
author | Gerald Combs <gerald@wireshark.org> | 2014-01-27 04:34:25 +0000 |
---|---|---|
committer | Gerald Combs <gerald@wireshark.org> | 2014-01-27 04:34:25 +0000 |
commit | 5b17df040e3c137e188a5ce4e32d25c4bae3c303 (patch) | |
tree | 7ec7e7fd7e85805aef1b14112c3b10907a9dd12c /docbook/wsdg_src | |
parent | 5344e2f2fc4e17e1a287264f0529740d91768173 (diff) |
Restore an inadvertently deleted file.
svn path=/trunk/; revision=54972
Diffstat (limited to 'docbook/wsdg_src')
-rw-r--r-- | docbook/wsdg_src/WSDG_chapter_quick_setup.xml | 595 |
1 files changed, 595 insertions, 0 deletions
diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.xml b/docbook/wsdg_src/WSDG_chapter_quick_setup.xml new file mode 100644 index 0000000000..7ca8bf06da --- /dev/null +++ b/docbook/wsdg_src/WSDG_chapter_quick_setup.xml @@ -0,0 +1,595 @@ +<!-- WSDG Chapter Setup --> +<!-- $Id$ --> + +<chapter id="ChapterSetup"> + <title>Quick Setup</title> + <section id="ChSetupUNIX"> + <title>UNIX: Installation</title> + <para>All the tools required are usually installed on a UNIX + developer machine.</para> + <para>If a tool is not already installed on your system, you + will typically use the installation package from your + distribution (by your favourite package manager: aptitude, yum, + synaptics, ...).</para> + <para>If an install package is not available, or you have a + reason not to use it (maybe because it's simply too old), you + can install that tool from source code. The following sections + will provide you with the webpage addresses where you can get + these sources.</para> + </section> + <section id="ChSetupWin32"> + <title>Win32/64: Step-by-Step Guide</title> + <para>A quick setup guide for Win32 and Win64 with recommended + configuration.</para> + <warning> + <title>Warning!</title> + <para> + <command>Unless you know exactly what you are doing, you + should strictly follow the recommendations!</command> + </para> + </warning> + <section id="ChSetupMSVC"> + <title>Install Microsoft C compiler and SDK</title> + <para>You need to install, in exactly this order: + <orderedlist> + <listitem> + <para>C compiler: + <ulink url="http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express"> + Download</ulink> and install "Microsoft Visual C++ + 2010 Express Edition." (This is a very large download.)</para> + </listitem> + <listitem> + <para>Windows SDK for Windows 7, if you want to build 64-bit + binaries for Windows 7: + <ulink url="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"> + Download</ulink> and install "Microsoft Windows SDK for + Windows 7."</para> + <para>In case the install of the SDK fails go to software management and + remove the vc++2010 runtime and redist packages (don't worry, they + will be added back via the service pack later). If installation of + the SDK still fails, there may be a permission problem. See + <ulink url="http://ctrlf5.net/?p=184">here</ulink> how to resolve + that.</para> + </listitem> + <listitem> + <para>C compiler service pack: + <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=23691"> + Download</ulink> and install "Microsoft Visual Studio 2010 + Service Pack 1." (This is a very large download.)</para> + </listitem> + <listitem> + <para>Microsoft Visual C++ 2010 Service Pack 1 Compiler Update + for the Windows SDK 7.1, if you want to build 64-bit + binaries for Windows 7: + <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=4422"> + Download</ulink> and install "Microsoft Visual C++ 2010 + Service Pack 1 Compiler Update for the Windows SDK 7.1."</para> + </listitem> + <!-- + <listitem> + <para>Platform SDK : + <ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en"> + Download</ulink>(420MB) and install "Microsoft Platform + SDK Server 2003 R2"</para> + </listitem> + --> + </orderedlist></para> + <para>If you will be building 64-bit binaries, those items must be + installed in that order, as installing the Microsoft Visual Studio + 2010 Service Pack 1 can, if you've installed the Microsoft Windows + SDK for Windows 7, remove the 64-bit compilers, as per + <ulink url="http://support.microsoft.com/?kbid=2519277">the + Microsoft Knowledge Base article "FIX: Visual C++ compilers are + removed when you upgrade Visual Studio 2010 Professional or Visual + Studio 2010 Express to Visual Studio 2010 SP1 if Windows SDK v7.1 + is installed"</ulink>. The release notes for the Microsoft Visual + C++ 2010 Service Pack 1 Compiler Update for the Windows SDK 7.1 + say that, to ensure that your system has a supported + configuration, you must install the items in the order specified + above. If you have Microsoft Update installed, so that the + Windows update process will update software other than components + of Windows, and thus will update Visual Studio, you may need to + disable it until after all of the above are installed, to make + sure it doesn't install Visual Studio 2010 SP1 out of order.</para> + <tip> + <title>You can use other Microsoft C compiler variants!</title> + <para>It's possible to compile Wireshark with a wide range + of Microsoft C compiler variants. For details see + <xref linkend="ChToolsMSChain" />!</para> + </tip> + <warning> + <title>Don't use Cygwin's gcc!</title> + <para>Using Cygwin's gcc is not recommended and will + certainly not work (at least without a lot of advanced + tweaking). For further details on this topic, see + <xref linkend="ChToolsGNUChain" />.</para> + </warning> + <para>XXX - mention the compiler and PSDK web installers - + which significantly reduce download size - and find out the + required components</para> + <para>Why is this recommended? While this is a huge download, + the 2010 Express Edition is the only free (as in beer) + version that includes the Visual Studio integrated + debugger. Visual C++ 2010 is also used to create official + Wireshark builds, so it will likely have fewer development-related + problems.</para> + </section> + <section id="ChSetupCygwin"> + <title>Install Cygwin</title> + <para> + <ulink url="http://www.cygwin.com/setup.exe"> + Download</ulink> the Cygwin installer and start it.</para> + <para>At the "Select Packages" page, you'll need to select + some additional packages which are not installed by default. + Navigate to the required Category/Package row and, if the package + has a "Skip" item in the "New" column, click on the "Skip" item + so it shows a version number for: + <itemizedlist> + <listitem> + <para>Archive/unzip</para> + </listitem> + <listitem> + <para>Base/dos2unix</para> + </listitem> + <listitem> + <para>Devel/bison</para> + </listitem> + <listitem> + <para>Devel/flex</para> + </listitem> + <listitem> + <para>Devel/subversion (optional - see discussion about using Subversion below)</para> + </listitem> + <listitem> + <para>Interpreters/perl</para> + </listitem> + <listitem> + <para>Utils/patch</para> + </listitem> + <listitem> + <para>Web/wget</para> + </listitem> + </itemizedlist></para> + <para>After clicking the Next button several times, the setup + will then download and install the selected packages (this + may take a while).</para> + <para>Why this is recommended: Cygwin's bash version is + required, as no native Win32 version is available. As + additional packages can easily be added, the perl and alike + packages are also used.</para> + </section> + <section id="ChSetupPython"> + <title>Install Python</title> + <para>Get the Python 2.7 installer from: + <ulink url="http://python.org/download/" /> and install Python + into the default location (C:\Python27).</para> + <para>Why this is recommended: Cygwin's Python package + doesn't work on some machines, so the Win32 native package is + recommended.</para> + </section> + <section id="ChSetupsubversion"> + <title>Install Subversion Client</title> + <para>Please note that the following is not required to build + Wireshark, but can be quite helpful when working with the + sources.</para> + <para>Working with the Subversion source repositories is highly + recommended, see <xref linkend="ChSrcObtain" />. It is much easier + to update a personal source tree with Subversion rather than downloading + a zip file and merging new sources into a personal source tree + "by hand." It also makes first-time setup easy and enables + the Wireshark build process to determine your current source code + revision.</para> + <para>There are several ways in which Subversion can be + installed:</para> + <section> + <title>Subversion from Cygwin</title> + <para>Cygwin comes with a command-line Subversion client. To install + it, run Cygwin's setup.exe, navigate to Devel/subversion, and + if the package has a "Skip" item in the "New" column, click on the + "Skip" item so it shows a version number.</para> + </section> + <section> + <title>Subversion from apache.org</title> + <para>There are several binary-distribution Subversion clients + available from apache.org. Go to + <ulink url="http://subversion.apache.org/" /> and simply + install one.</para> + </section> + <section> + <title>TortoiseSVN</title> + <para>TortoiseSVN is a native Windows graphical Subversion client for + Windows. You can download the setup from + <ulink url="http://tortoisesvn.net/" /> and simply + install it.</para> + </section> + </section> + <section> + <title>Install and Prepare Sources</title> + <para> + <tip> <title>Tip</title> + <para>It's a good idea to successfully compile and run + Wireshark at least once before you start hacking the + Wireshark sources for your own project! This example uses TortoiseSVN + but another Subversion client would work as well.</para> + </tip> + <orderedlist> + <listitem> + <para>Download sources : Download Wireshark sources into: + <filename>C:\wireshark</filename> using TortoiseSVN</para> + <para> + <orderedlist> + <listitem> + <para>right click on the C:\ drive in Windows + Explorer</para> + </listitem> + <listitem> + <para>in the upcoming context menu select "SVN + checkout..." and then set:</para> + </listitem> + <listitem> + <para> + <orderedlist> + <listitem> + <para>URL of repository: " + <literal> + http://anonsvn.wireshark.org/wireshark/trunk/</literal>"</para> + </listitem> + <listitem> + <para>Checkout directory: + <filename>C:\wireshark</filename></para> + </listitem> + </orderedlist> + </para> + </listitem> + <listitem> + <para>TortoiseSVN might ask you to create this + directory - say yes</para> + </listitem> + <listitem> + <para>TortoiseSVN starts downloading the sources</para> + </listitem> + <listitem> + <para>if the download fails you may be behind a + restrictive firewall, see + <xref linkend="ChSrcObtain" /> for alternative + download methods</para> + </listitem> + </orderedlist> + </para> + </listitem> + <listitem> + <para>Edit config.nmake: edit the settings in + <filename>C:\wireshark\config.nmake</filename>, especially:</para> + <para> + <orderedlist> + <listitem> + <para><varname>VERSION_EXTRA</varname> : Give Wireshark your "private" + version info, e.g.: -myprotocol123 - to distinguish + it from an official release!</para> + </listitem> + <listitem> + <para><varname>PROGRAM_FILES</varname> : Where your programs reside, + usually just keep the default: <filename>C:\Program Files</filename> + <superscript>1</superscript></para> + </listitem> + <listitem> + <para><varname>MSVC_VARIANT</varname> : Make sure the variant for + your compiler is + uncommented, and that all others are commented out. For example, + if you're using Visual C++ 2010 Express Edition, find the line + <programlisting> +<![CDATA[#MSVC_VARIANT=MSVC2010EE]]> + </programlisting> + and remove the comment character (#) + from the beginning of the line. Then, find the line + <programlisting> +<![CDATA[MSVC_VARIANT=MSVC2010]]> + </programlisting> + and comment it out, by prefixing a hash (#). + <superscript>2</superscript></para> + </listitem> + </orderedlist> + </para> + </listitem> + </orderedlist> + <superscript>1</superscript>International Windows might use + different values here, e.g. a German version uses + <filename>C:\Programme</filename> - take this also in account where + <filename>C:\Program Files</filename> appears elsewhere.</para> + <para> + <superscript>2</superscript>Compiler dependent: This step + depends on the compiler you are using. For compilers other than + Visual C++ 2010, see the table at + <xref linkend="ChToolsMSChain" />.</para> + </section> + <section id="ChSetupPrepareCommandCom"> + <title>Prepare cmd.exe</title> + <para>Prepare <filename>cmd.exe</filename> - set environment and current dir. + <orderedlist> + <listitem> + <para>start <command>cmd.exe</command></para> + </listitem> + <!-- + <listitem> + <para>call "C:\Program Files\Microsoft Platform SDK for + Windows Server 2003 R2\SetEnv.Cmd" to set environment + variables of Platform SDK Server 2003 R2 + <superscript>1,2</superscript></para> + </listitem> + --> + <listitem> + <para>set environment variables for Visual C++ 2010 Express + Edition:<superscript>1,2</superscript></para> + <para>to build 32-bit binaries call + <command>"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x86</command> + and to build 64-bit binaries call + <command>"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x64</command></para> + <para>If your version of the compiler does not have <filename>SetEnv.Cmd</filename>, you + may need to use <filename>vcvarsall.bat</filename> or <filename>vcvars32.bat</filename> + which do much the same thing as <filename>SetEnv.cmd</filename>.</para> + <para> + For example, on some 64-bit installations, one would build a 32-bit version + by invoking + <command>C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat</command> + and one would build a 64-bit version using the command + <command>C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\Vcvarsall.bat amd64</command> + Consult your compiler's documentation to learn which version applies to your installation.</para> + </listitem> + <listitem> + <para>set environment variable to select target platform</para> + <para>to build 32-bit binaries execute + <command>set WIRESHARK_TARGET_PLATFORM=win32</command> + and to build 64-bit binaries execute + <command>set WIRESHARK_TARGET_PLATFORM=win64</command></para> + </listitem> + <listitem> + <para><command>cd C:\wireshark</command> to jump into the source + directory</para> + </listitem> + </orderedlist> + <superscript>1</superscript>International Windows might use + different values here, e.g. a German version uses + <filename>C:\Programme</filename> - take this also in account where + <filename>C:\Program Files</filename> appears elsewhere. Note: You need + to repeat steps 1 - 4 each time you open a new cmd.exe!</para> + <para><superscript>2</superscript>Compiler dependent: This step + depends on the compiler variant used, for other variants than + the recommended Visual C++ 2010 Express Edition see the table + at + <xref linkend="ChToolsMSChain" />!</para> + + <para>Wireshark development depends on several additional + environment variables, particularly <varname>PATH</varname>. + You can use a batch script to fill these in, along with the Visual + C++ variables; for example: + + <programlisting> +<![CDATA[@echo off + +if "%1" == "" goto x86 +if /i %1 == x86 goto x86 +if /i %1 == x64 goto x64 +goto usage + +:usage +echo Error in script usage. The correct usage is: +echo %0 [option] +echo where [option] is: x86 ^| x64 +echo: +echo For example: +echo %0 x86 +goto :eof + +:x64 +echo Adding things to the path... +set PATH=%PATH%;c:\cygwin\bin +set WIRESHARK_TARGET_PLATFORM=win64 +call "c:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x64 +title Command Prompt (VC++ 2010 x64) +goto :eof + +:x86 +echo Adding things to the path... +set PATH=%PATH%;c:\cygwin\bin +set WIRESHARK_TARGET_PLATFORM=win32 +call "c:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Release /x86 +title Command Prompt (VC++ 2010 -x86) +goto :eof]]> + + </programlisting> + </para> + </section> + <section id="ChToolsWin32Verify"> + <title>Verify installed tools</title> + <para>After you've installed the Wireshark sources (see + <xref linkend="ChSrcObtain" />), you can check the correct + installation of all tools by using the <parameter>verify_tools</parameter> + target of the + <filename>Makefile.nmake</filename> from the source package.</para> + <warning> + <title>Warning!</title> + <para>You will need the Wireshark sources and some tools + (nmake, bash) installed, before this verification is able + to work.</para> + </warning> + <para>Enter at the command line (cmd.exe, not Cygwin's bash!):</para> + <para> + <prompt>></prompt> + <userinput>nmake -f Makefile.nmake verify_tools</userinput> + </para> + <para>This will check for the various tools needed to build Wireshark:</para> + <para> + <programlisting> +<![CDATA[Checking for required applications: + cl: /cygdrive/c/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/cl + link: /cygdrive/c/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/link + nmake: /cygdrive/c/Program Files (x86)/Microsoft Visual Studio 10.0/VC/Bin/amd64/nmake + bash: /usr/bin/bash + bison: /usr/bin/bison + flex: /usr/bin/flex + env: /usr/bin/env + grep: /usr/bin/grep + /usr/bin/find: /usr/bin/find + peflags: /usr/bin/peflags + perl: /usr/bin/perl + C:\Python27\python.exe: /cygdrive/c/Python27/python.exe + sed: /usr/bin/sed + unzip: /usr/bin/unzip + wget: /usr/bin/wget]]> + </programlisting> + </para> + <para>If you have problems with all the first three items (cl, link, nmake), + check that you called <command>SetEnv.Cmd</command> + as mentioned in + <xref linkend="ChSetupPrepareCommandCom" /> (which will "fix" + your <varname>PATH</varname> settings). However, the exact text will be slightly + different depending on the MSVC version used.</para> + <para>Unfortunately, the link command is defined both in + Cygwin and in MSVC each with completely different functionality; + you'll need the MSVC link. If your link command looks + something like: <command>/usr/bin/link</command>, the link command of Cygwin + takes precedence over the MSVC one. To fix this, you can + change your <varname>PATH</varname> environment setting or simply rename the + <filename>link.exe</filename> in Cygwin. If you rename it, make sure to remember + that a Cygwin update may provide a new version of it.</para> + <para>Make sure that the other tools found are the Cygwin versions. Some build + problems have been caused by incompatible versions of <command>grep</command> and + <command>unzip</command>.</para> + </section> + <section> + <title>Install Libraries</title> + <orderedlist> + <listitem> + <para>If you've closed <command>cmd.exe</command> in the meantime, + prepare <command>cmd.exe</command> again.</para> + </listitem> + <listitem> + <para><command>nmake -f Makefile.nmake setup</command> downloads libraries + using <command>wget</command> and installs them - this may take a while + ...</para> + </listitem> + <listitem> + <para>If the download fails you may be behind a + restrictive firewall, see the proxy comment in + <xref linkend="ChToolsWget"/>.</para> + </listitem> + </orderedlist> + <para>Note that 32-bit versions of the software require 32-bit versions of the + libraries and that 64-bit versions require 64-bit libraries. The build process + creates independent directories for each as needed. See + <xref linkend="ChSetupPrepareCommandCom" /> for how to use + <command>SetEnv.Cmd</command> and <varname>WIRESHARK_TARGET_PLATFORM</varname> + to select either a 32- or 64-bit build.</para> + </section> + <section> + <title>Distclean Sources</title> + <para>The released Wireshark sources contain files that are + prepared for a UNIX build (e.g. <filename>config.h</filename>).</para> + <para>You must distclean your sources before building the + first time! + <orderedlist> + <listitem> + <para>If you've closed <command>cmd.exe</command> in the meantime, + prepare <command>cmd.exe</command> again</para> + </listitem> + <listitem> + <para><command>nmake -f Makefile.nmake distclean</command> + to cleanup the Wireshark sources</para> + </listitem> + </orderedlist></para> + </section> + <section> + <title>Build Wireshark</title> + <para>Now it's time to build Wireshark ... + <orderedlist> + <listitem> + <para>If you've closed <command>cmd.exe</command> in the meantime, + prepare <command>cmd.exe</command> again</para> + </listitem> + <listitem> + <para><command>nmake -f Makefile.nmake all</command> + to build Wireshark</para> + </listitem> + <listitem> + <para>wait for Wireshark to compile - this may take a + while!</para> + </listitem> + <listitem> + <para>run <command>C:\wireshark\wireshark-gtk2\wireshark.exe</command> + and check if it starts</para> + </listitem> + <listitem> + <para>check Help/About if it shows your "private" program + version, e.g.: Version &WiresharkCurrentVersion;.x-myprotocol123 + - you might run a release version previously installed!</para> + </listitem> + </orderedlist>Tip: If compilation fails for suspicious + reasons after you changed some source files try to "distclean" + the sources and make "all" again</para> + </section> + <section> + <title>Debug Environment Setup (XXX)</title> + <para>XXX - debug needs to be written, e.g. an idea is the + create a simple MSVC workspace/project(s) to ease Visual + Studio debugging</para> + </section> + <section> + <title>Optional: Create User's and Developer's Guide</title> + <para>Detailed information to build these guides can be found in the file + <filename>docbook/README.txt</filename> in the Wireshark sources.</para> + </section> + <section> + <title>Optional: Create a Wireshark Installer</title> + <para>Note: You should have successfully built Wireshark + before doing the following!</para> + <para>If you want to build your own + <filename>wireshark-win32-&WiresharkCurrentVersion;.x-myprotocol123.exe</filename>, + you'll need NSIS. + <orderedlist> + <listitem> + <para>NSIS: + <ulink url="http://nsis.sourceforge.net"> + Download</ulink> and install NSIS</para> + <para>You may check the <varname>MAKENSIS</varname> setting in the file + <filename>config.nmake</filename> of the Wireshark sources. Note that the + 32-bit version of NSIS will work for both 32-bit and 64-bit versions of + Wireshark.</para> + </listitem> + <listitem> + <para>Runtime redistributable: to build a 32-bit version you will need + <filename>vcredist_x86.exe</filename> : + <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=8328"> + Download</ulink> the C-Runtime redistributable for Visual + C++ 2010 Express Edition SP1 (<filename>vcredist_x86.exe</filename>) + and copy it into <filename>C:\wireshark-win32-libs</filename> + <superscript>1</superscript></para> + <para>To build a 64-bit version, you will need + <filename>vcredist_x64.exe</filename> : + <ulink url="http://www.microsoft.com/en-us/download/details.aspx?id=13523"> + Download</ulink> the 64-bit redistributable for Visual C++ 2010 Express + Edition SP1 (<filename>vcredist_x64.exe</filename>) and copy it into + <filename>C:\Wireshark-win64-libs</filename><superscript>1</superscript> + </para> + </listitem> + <listitem> + <para>If you've closed <command>cmd.exe</command> in the meantime, + prepare <command>cmd.exe</command> again</para> + </listitem> + <listitem> + <para><command>nmake -f Makefile.nmake packaging</command> + build Wireshark installer</para> + </listitem> + <listitem> + <para>run + <command>C:\wireshark\packaging\nsis\wireshark-win32-&WiresharkCurrentVersion;.x-myprotocol123.exe</command> + and test it - it's a good idea to test also on a different machine + than the developer machine.</para> + </listitem> + </orderedlist> + <superscript>1</superscript>Compiler dependent: This step + depends on the compiler variant used; for other variants than + the recommended Visual C++ 2010 Express Edition SP1 see the table + at <xref linkend="ChToolsMSChain" />!</para> + </section> + </section> +</chapter> |