<chapter><title>Porting VLC</title>

  <sect1> <title> Port steps </title>

    <para>
Basically, porting to a new architecture boils down to follow the
following steps :
    </para>

    <orderedlist>

      <listitem> <para> <emphasis> Building the VLC : </emphasis>
      That may be the most difficult part, depending on how POSIX
      the architecture is. You have to produce valid C.
      </para> </listitem>

      <listitem> <para> <emphasis> Having video : </emphasis>
      If your architecture features an X server, it should be
      straightforward, though you might have problems with xvideo
      or xshm. Otherwise you can try to use SDL if it is supported,
      or end up writing your own video output plugin.
      </para> </listitem>

      <listitem> <para> <emphasis> Having audio : </emphasis>
      If your architecture features an OSS compatible DSP or ALSA, you
      can reuse an existing plugin. Otherwise you will have to write
      your own audio output plugin.
      </para> </listitem>

      <listitem> <para> <emphasis> Accessing DVDs : </emphasis>
      You are going to need a write access to the DVD device.
      Every system has specific ioctl() for key negociation with
      the DVD drive, so we have set up an abstration layer in
      <filename> plugins/dvd/dvd_ioctl.c</filename>. You might
      need to add stuff here. Some operating systems won't give
      you access to the key negociation (MacOS X), so you will
      have to write a kernel extension or you will only be able to read
      unencrypted DVDs. Other operating systems might only give
      you read access to the DVD device if you are root. Your mileage
      may vary.
      </para> </listitem>

      <listitem> <para> <emphasis> Writing a native interface : </emphasis>
      If your system doesn't support GTK or Qt, you will have to
      write a native interface plugin (for instance Aqua or Win32).
      You may also need to rewrite the video output plugin if
      you're currently using a slow compatibility layer.
      </para> </listitem>

      <listitem> <para> <emphasis> Optimizing : </emphasis>
      If your architecture features a special set of multimedia
      instructions (such as MMX) that is not supported by VLC, you
      may want to write specific optimizations. Heavy calculation
      parts are : IDCT (see idct plugin), motion compensation
      (see motion plugin), and YUV (see video output) if you don't
      use the YUV overlay support of your video board (SDL or
      XVideo extension).
      </para> </listitem>

    </orderedlist>

  </sect1>

  <sect1> <title> Building </title>

    <para>
This is probably the most complicated part. If your platform is fully
POSIX-compliant (such as GNU/Linux), it should be quick, otherwise
expect troubles. Known issues are :
    </para>

    <itemizedlist>

      <listitem> <para> Finding a compiler : We use <application> gcc
      </application> on all platforms, and <application> mingw32
      </application> to cross-compile the win32 port. If you don't you're
      probably in <emphasis> very big </emphasis> trouble. Good luck.
      </para> </listitem>

      <listitem> <para> Finding <application> GNU make </application> : Our
      <filename>Makefile</filename> is heavily <application>GNU make
      </application> specific, so I suggest you install it.
      </para> </listitem>

      <listitem> <para> Running the <filename> configure </filename>
      script : This is basically a shell script, so if you have a UNIX
      shell on your platform it shouldn't be a problem. It will probe
      your system for headers and libraries needed. It needs
      adequate <filename> config.sub </filename> and <filename>
      config.guess</filename>, so if your platform is young your
      provider may have supplied customized versions. Check with it.
      </para> </listitem>

      <listitem> <para> Compiling the VLC binary : This is the most
      difficult. Type <command> make </command> or <command> gmake
      </command> and watch the results. It will probably break soon
      on a parse error. Add the headers missing, fix mistakes. If
      you cannot make it to also compiles on other platforms, use
      #ifdef directives. Add tests for functions or libraries in
      <filename> configure.in </filename> and run <command> autoheader
      </command> and <command> autoconf</command>. Always prefer
      tests on <property> #ifdef HAVE_MY_HEADER_T</property>,
      instead of <property> #ifdef SYS_MYOPERATINGSYSTEM</property>.
      You may especially experience problems with the network code
      in <filename> src/input/input.c</filename>.
      </para> </listitem>

      <listitem> <para> Threads : If your system has an exotic thread
      implementation, you will probably need to fill the wrappers in
      <filename> include/threads.h </filename> for your system.
      Currently supported implementations include the POSIX pthreads,
      the BeOS threads, and the Mach cthreads.
      </para> </listitem>

      <listitem> <para> Linking : You will need special flags to the
      compiler, to allow symbol exports (otherwise plug-ins won't
      work). For instance under GNU/Linux you need <parameter>
      -rdynamic</parameter>.
      </para> </listitem>

      <listitem> <para> Compiling plug-ins : You do not need external
      plug-ins at first, you can build all you need in (see <filename>
      Makefile.opts</filename>). In the long run though, it is a
      good idea to change <parameter> PCFLAGS</parameter> and <parameter>
      PLCFLAGS</parameter> to allow run-time loading of libraries.
      You are going to need <application> libdl</application>, or a
      similar dynamic loader. To add support for an exotic dynamic
      loader, have a look at <filename> include/modules_core.h
      </filename>. Currently supported implementations include the
      UNIX dynamic loader and the BeOS image loader.
      </para> </listitem>

      <listitem> <para> Assembling : If you use specific optimizations
      (such as MMX), you may have problem assembling files, because
      the assembler syntax may be different on your platform. Try
      without it at first. Pay attention to the optimization flags
      too, you may see a <emphasis>huge</emphasis> difference.
      </para> </listitem>

    </itemizedlist>

    <para>
VLC should work both on little endian and big endian systems. All
load operations should be aligned on the native size of the type, so
that it works on exotic processors like Sparc or Alpha. It should
work on 64-bit platforms, though it has not been optimized for it.
A big boost for them would be to have a WORD_TYPE = u64 in <filename>
include/input_ext-dec.h</filename>, but it is currently broken for
unknown reasons.
    </para>

    <para>
If you experience run-time problems, see the following appendix and
pray for you to have <command> gdb</command>...
    </para>

  </sect1>


</chapter>
