diff options
| -rw-r--r-- | docbook/CMakeLists.txt | 5 | ||||
| -rw-r--r-- | docbook/Makefile.am | 2 | ||||
| -rw-r--r-- | docbook/Makefile.common | 5 | ||||
| -rw-r--r-- | docbook/Makefile.nmake | 2 | ||||
| -rw-r--r-- | docbook/asciidoc.conf | 7 | ||||
| -rw-r--r-- | docbook/wsdg_src/WSDG_chapter_quick_setup.xml | 595 | ||||
| -rw-r--r-- | docbook/wsdg_src/WSDG_preface.asciidoc | 112 | ||||
| -rw-r--r-- | docbook/wsdg_src/WSDG_preface.xml | 129 |
8 files changed, 127 insertions, 730 deletions
diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index ddecc337f0..b85f2ec78b 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -193,12 +193,13 @@ set(WSDG_FILES wsdg_src/WSDG_chapter_userinterface.xml wsdg_src/WSDG_chapter_works.xml wsdg_src/WSDG_meta_info.xml - wsdg_src/WSDG_preface.xml + wsdg_generated_src/WSDG_preface.xml ws.css ) set(WSDG_ASCIIDOC_FILES wsdg_src/WSDG_chapter_sources.asciidoc + wsdg_src/WSDG_preface.asciidoc ) set(WSDG_GRAPHICS @@ -247,7 +248,7 @@ MACRO( ASCIIDOC2CHAPTER _asciidocsource _conffile ) ${_output_xml} ${_output_dbk} COMMAND ${XMLLINT_EXECUTABLE} - --xpath //chapter + --xpath '//chapter | //preface' ${_output_dbk} > ${_output_xml} DEPENDS diff --git a/docbook/Makefile.am b/docbook/Makefile.am index dd4dad35e7..1ff11bde24 100644 --- a/docbook/Makefile.am +++ b/docbook/Makefile.am @@ -64,7 +64,7 @@ endif --format=docbook --doctype=book \ $< mv $*.xml $*.dbk - xmllint --xpath //chapter $*.dbk > $@ + xmllint --xpath '//chapter | //preface' $*.dbk > $@ if HAVE_XSLTPROC ALL_TARGETS=git_version_check wsug wsdg release_notes diff --git a/docbook/Makefile.common b/docbook/Makefile.common index 77a62cff60..4391ff01d5 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -170,11 +170,12 @@ WSDG_FILES = \ wsdg_src/WSDG_chapter_userinterface.xml \ wsdg_src/WSDG_chapter_works.xml \ wsdg_src/WSDG_meta_info.xml \ - wsdg_src/WSDG_preface.xml \ + wsdg_src/WSDG_preface.asciidoc \ ws.css WSDG_GENERATED_SOURCE = \ - wsdg_src/WSDG_chapter_sources.xml + wsdg_src/WSDG_chapter_sources.xml \ + wsdg_src/WSDG_preface.xml WSDG_GRAPHICS = \ wsdg_graphics/ws-capture-sync.dia \ diff --git a/docbook/Makefile.nmake b/docbook/Makefile.nmake index 58b0fac892..c9ede09172 100644 --- a/docbook/Makefile.nmake +++ b/docbook/Makefile.nmake @@ -44,7 +44,7 @@ A2X_TEXT_OPTS=$(A2X_TEXT_OPTS) --lynx $< << mv $*.xml $*.dbk - xmllint --xpath //chapter $*.dbk > $@ + xmllint --xpath '//chapter | //preface' $*.dbk > $@ .SUFFIXES: .asciidoc .xml diff --git a/docbook/asciidoc.conf b/docbook/asciidoc.conf index 5be3772e8f..29595a1c58 100644 --- a/docbook/asciidoc.conf +++ b/docbook/asciidoc.conf @@ -4,6 +4,7 @@ [replacements] # Yes, these are fake macros. +# We should probably replace some or all of them with attributes. wireshark-version:\[\]=1.11.3 wireshark-major-minor-version:\[\]=1.11 @@ -14,8 +15,14 @@ wireshark-git-http-url:\[\]=https://your.username@code.wireshark.org/review/wire wireshark-git-ssh-url:\[\]=ssh://your.username@code.wireshark.org:29418/wireshark wireshark-code-review-url:\[\]=https://code.wireshark.org/review wireshark-code-browse-url:\[\]=https://code.wireshark.org/review/gitweb?p=wireshark.git +wireshark-users-guide-url:\[\]=http://www.wireshark.org/docs/ +wireshark-developers-guide-url:\[\]=http://www.wireshark.org/docs/ wireshark-web-site:\[\]=http://www.wireshark.org/ wireshark-wiki-site:\[\]=http://wiki.wireshark.org/ +wireshark-dev-list-email:\[\]=wireshark-dev[AT]wireshark.org + +# Make a document attribute after we fully convert to AsciiDoc +wsdg-author-email:\[\]=ulf.lamping[AT]web.de [macros] diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.xml b/docbook/wsdg_src/WSDG_chapter_quick_setup.xml deleted file mode 100644 index 7ca8bf06da..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_quick_setup.xml +++ /dev/null @@ -1,595 +0,0 @@ -<!-- 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> diff --git a/docbook/wsdg_src/WSDG_preface.asciidoc b/docbook/wsdg_src/WSDG_preface.asciidoc new file mode 100644 index 0000000000..1fdc7b8a66 --- /dev/null +++ b/docbook/wsdg_src/WSDG_preface.asciidoc @@ -0,0 +1,112 @@ + + +++++++++++++++++++++++++++++++++++++++ +<!-- $Id$ --> +++++++++++++++++++++++++++++++++++++++ + +[[Preface]] + +[preface] +== Preface + +[[PreForeword]] + +=== Foreword + +This book tries to give you a guide to start your own experiments into +the wonderful world of Wireshark development. + +Developers who are new to Wireshark often have a hard time getting +their development environment up and running. This is +especially true for Win32 developers, as a lot of the tools and methods +used when building Wireshark are much more common in the UNIX world than +on Win32. + +The first part of this book will describe how to set up the environment +needed to develop Wireshark. + +The second part of this book will describe how to change the Wireshark +source code. + +We hope that you find this book useful, and look forward to your comments. + +[[PreAudience]] + +=== Who should read this document? + +The intended audience of this book is anyone going into the development of +Wireshark. + +This book is not intended to explain the usage of Wireshark in general. +Please refer the +wireshark-users-guide-url:[][Wireshark User's Guide] about Wireshark usage. + +By reading this book, you will learn how to develop Wireshark. It will +hopefully guide you around some common problems that frequently appear for +new (and sometimes even advanced) developers of Wireshark. + +[[PreAck]] + +=== Acknowledgements + +The authors would like to thank the whole Wireshark team for their +assistance. In particular, the authors would like to thank: + +* Gerald Combs, for initiating the Wireshark project. + +* Guy Harris, for many helpful hints and his effort in maintaining +the various contributions on the mailing lists. + +The authors would also like to thank the following people for their +helpful feedback on this document: + +* XXX - Please give feedback :-) + +And of course a big thank you to the many, many contributors of the +Wireshark development community! + +[[PreAbout]] + +=== About this document + +// XXX - Convert to document attribute +This book was developed by mailto:wsdg-author-email:[][Ulf Lamping]. + +It is written in AsciiDoc. + +You will find some specially marked parts in this book: + +[WARNING] +.This is a warning +==== +You should pay attention to a warning, as otherwise data loss might occur. +==== + +[NOTE] +.This is a note +==== +A note will point you to common mistakes and things that might not be +obvious. +==== + +[TIP] +.This is a tip +==== +Tips will be helpful for your everyday work developing Wireshark. +==== + +[[PreDownload]] + +=== Where to get the latest copy of this document? + +The latest copy of this documentation can always be found at: +wireshark-developers-guide-url:[] in A4 PDF, US letter PDF, single HTML, and chunked HTML. + +[[PreFeedback]] + +=== Providing feedback about this document + +Should you have any feedback about this document, please send it +to the authors through mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]]. + + diff --git a/docbook/wsdg_src/WSDG_preface.xml b/docbook/wsdg_src/WSDG_preface.xml deleted file mode 100644 index 7c8cded6d8..0000000000 --- a/docbook/wsdg_src/WSDG_preface.xml +++ /dev/null @@ -1,129 +0,0 @@ -<!-- $Id$ --> - -<preface id="Preface"> - <title>Preface</title> - <section id="PreForeword"> - <title>Foreword</title> - <para> - This book tries to give you a guide to start your own experiments into - the wonderful world of Wireshark development. - </para> - <para> - Developers who are new to Wireshark often have a hard time getting - their development environment up and running. This is - especially true for Win32 developers, as a lot of the tools and methods - used when building Wireshark are much more common in the UNIX world than - on Win32. - </para> - <para> - The first part of this book will describe how to set up the environment - needed to develop Wireshark. - </para> - <para> - The second part of this book will describe how to change the Wireshark - source code. - </para> - <para> - We hope that you find this book useful, and look forward to your comments. - </para> - </section> - - <section id="PreAudience"> - <title>Who should read this document?</title> - <para> - The intended audience of this book is anyone going into the development of - Wireshark. - </para> - <para> - This book is not intended to explain the usage of Wireshark in general. - Please refer the - <ulink url="&WiresharkUsersGuidePage;">Wireshark User's Guide</ulink> - about Wireshark usage. - </para> - <para> - By reading this book, you will learn how to develop Wireshark. It will - hopefully guide you around some common problems that frequently appear for - new (and sometimes even advanced) developers of Wireshark. - </para> - </section> - - <section id="PreAck"> - <title>Acknowledgements</title> - <para> - The authors would like to thank the whole Wireshark team for their - assistance. In particular, the authors would like to thank: - <itemizedlist> - <listitem> - <para> - Gerald Combs, for initiating the Wireshark project. - </para> - </listitem> - <listitem> - <para> - Guy Harris, for many helpful hints and his effort in maintaining - the various contributions on the mailing lists. - </para> - </listitem> - </itemizedlist> - </para> - <para> - The authors would also like to thank the following people for their - helpful feedback on this document: - <itemizedlist> - <listitem> - <para>XXX - Please give feedback :-) - </para> - </listitem> - </itemizedlist> - And of course a big thank you to the many, many contributors of the - Wireshark development community! - </para> - </section> - - <section id="PreAbout"> - <title>About this document</title> - <para> - This book was developed by - <ulink url="mailto:&AuthorEmail;">Ulf Lamping</ulink>. - </para> - <para> - It is written in DocBook/XML. - </para> - <para> - You will find some specially marked parts in this book: - </para> - <warning><title>This is a warning!</title> - <para> - You should pay attention to a warning, as otherwise data loss might occur. - </para> - </warning> - <note><title>This is a note!</title> - <para> - A note will point you to common mistakes and things that might not be - obvious. - </para> - </note> - <tip><title>This is a tip!</title> - <para> - Tips will be helpful for your everyday work developing Wireshark. - </para> - </tip> - </section> - - <section id="PreDownload"> - <title>Where to get the latest copy of this document?</title> - <para> - The latest copy of this documentation can always be found at: - <ulink url="&WiresharkDevsGuidePage;">&WiresharkDevsGuidePage;</ulink> - in PDF (A4 and US letter), HTML (single and chunked) and CHM format. - </para> - </section> - - <section id="PreFeedback"> - <title>Providing feedback about this document</title> - <para> - Should you have any feedback about this document, please send it - to the authors through <ulink url="mailto:&WiresharkDevMailList;">&WiresharkDevMailList;</ulink>. - </para> - </section> -</preface> |