======================================================================
README for mod_uploader (Windows)
======================================================================

.. image:: img/title.png
   :width: 440
   :height: 89
   :alt: mod_uploader: Apache のモジュールとして動作する高速アップローダ

.. contents::


mod_uploader とは?
----------------------------------------------------------------------

mod_uploader は，よくあるアップローダを `Apache`_ のモジュールとして実
装したものです．以下のような特長があります．

* 依存しているライブラリ等が少ないので初心者でも設置が簡単．
  (Perl や PHP のインストールは不要です)

* `Apache`_ のモジュールとして C++ で記述されているので，Perl や PHP で
  作られた物に比べて高速．

* 独自の簡易スクリプト言語によるテンプレート機能があるので，再コンパイ
  ル無しで手軽に見た目を変更可能．

* アップロード時の進捗状況をリアルタイムに表示可能．
  
.. image:: img/upload_window.png
   :width: 683
   :height: 145
   :alt: アップロード画面のスクリーンショット


機能比較
----------------------------------------------------------------------

他のアップローダとの機能比較を下記に示します．

.. image:: img/func_comparison.png
   :width: 820
   :height: 161
   :alt: 他のアップローダとの機能比較


動作サンプル
----------------------------------------------------------------------

http://acapulco.dyndns.org:7070/up/


動作環境
----------------------------------------------------------------------

.. |IconLinux| image:: img/icon_linux.png
   :width: 16
   :height: 16
   :alt: Linux

mod_uploader は，Windows で動作します．(|IconLinux| `UNIX 版はこちら <http://acapulco.dyndns.org/mod_uploader/>`_)

詳細を以下に示します．

* `Microsoft Windows`_ XP 以上

* `Apache`_ 2.2 以上
  [ `Apache インストール手順 <install_apache.htm>`_ ]

* `ImageMagick`_  6.0 以上 (``Dynamic at 8 bits-per-pixel``)
  [ `ImageMagick インストール手順 <install_imagemagick.htm>`_ ]

* `.NET Framework`_ 2.0 以上 (設定情報生成ツールを使用しない場合は不要)
  
* `Visual C++ .NET`_ 2005 以上（コンパイルしない場合は不要）

* `Cygwin`_ 版 `GNU Make`_ 3.8 以上（コンパイルしない場合は不要）
  
ライセンス
----------------------------------------------------------------------

`The zlib/libpng License`_ （ `The zlib/libpng License の翻訳`_ ）に従
います．


ダウンロード
----------------------------------------------------------------------

* `mod_uploader-2.2.6.msi <http://prdownloads.sourceforge.jp/mod-uploader/23249/mod_uploader-2.2.6.msi>`_


CVS リポジトリ
----------------------------------------------------------------------

下記のようにすることで check out できます．（パスワードは空）

::

  $ cvs -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/mod-uploader login
  $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/mod-uploader co mod_uploader

また， `ViewCVS 経由で参照
<http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/mod-uploader/mod_uploader/>`_
することもできます．


インストール
----------------------------------------------------------------------

mod_uploader-2.2.6.msi を実行すれば OK です．デフォルトでは
`C:/Program Files/mod_uploader` 以下にインストールされます．

注意事項
``````````````````````````````````````````````````````````````````````
`動作環境`_ にも書いてありますが，あらかじめ Apache 及び ImageMagick を
インストールしておく必要があります．(参考: `Apache インストール手順
<install_apache.htm>`_, `ImageMagick インストール手順
<install_imagemagick.htm>`_)


設定
----------------------------------------------------------------------

.. |IconError| image:: img/icon_error.png
   :width: 20
   :height: 20
   :alt: エラーアイコン

1. [スタート] - [プログラム] - [mod_uploader] からたどれる
   UploaderConfig を起動します．起動すると下図の様なウィンドウが現れます．

.. image:: img/config_window.png
   :width: 463
   :height: 572
   :alt: UploaderConfig のスクリーンショット

2. 掲示板の URL を必要にあわせて変更します．他にも設定項目がありますが，
   通常は変更する必要ありません．

3. エラー |IconError| が表示されていれば，その項目を修正します．
   アイコンの上にカーソルをあわせると詳しい説明が表示されます．

4. 「設定をコピー」ボタンを押して設定をクリップボードにコピーします．

5. コピーしたものを Apache の設定ファイル (`httpd.conf`) に貼り付けます．


起動
----------------------------------------------------------------------  

`Apache`_ を普通に起動すれば OK です．設置した場所にブラウザでアクセス
してみましょう．


コンパイル方法
----------------------------------------------------------------------

通常はコンパイル作業は不要です．ソースを編集して細かくカスタマイズした
い方のみ読んでください．

最初に，UNIX 系 OS で configure します．

::

  $ ./configure

次に，ディレクトリを丸ごと Windows にコピーし，src/GNUmakefile.win32 の
次の部分を， `Apache`_ をインストールしたディレクトリおよび
`ImageMagick`_ をインストールしたディレクトリに書き換えます．

::

  APACHE_DIR  := C:/Server/Apache2
  MAGICK_DIR  := C:/Application/Image/Edit/ImageMagick

以上が完了したら，src/GNUmakefile.win32 を使って make します．

::

  > cd src
  > vsvars32.bat
  > make -f GNUmakefile.win32

`vsvars32.bat` は，コマンドラインから `Visual C++ .NET`_ を使うための環
境設定を行うスクリプトです． `Visual C++ .NET`_ をインストールしたディ
レクトリ以下の Common7/Tools にあります．


アンインストール
----------------------------------------------------------------------

[スタート] - [設定] - [コントロールパネル] にある「プログラムの追加と削
除」から行えます．掲示板のデータは自動的には消去されませんので完全に消
去したい場合は手動でフォルダ (デフォルトでは `C:/Program
Files/mod_uploader`) を削除してください．

注意事項
``````````````````````````````````````````````````````````````````````
mod_uploader が動作中だとアンインストールが行えません．アンインストール
作業が途中で止まってしまう場合は，httpd.conf から mod_uploader の設定を
削除した後 Apache を再起動し，再度試してみてください．


パフォーマンス
----------------------------------------------------------------------

高速な表示
```````````````````````````````````````````````````````````````````````

.. image:: img/speed.png
   :width: 460
   :height: 248
   :alt: 一秒間に処理できるリクエスト数
   :align: right
               
mod_uploader は，表示を非常に高速に行うことができます．

右に他のアップローダとの速度比較を示します．HTML は，表示を静的な HTML
で行うもの，Perl および PHP はそれぞれの言語で作られたアップローダを指
しています．測定には ApacheBench を用い，5 並列で 10,000 リクエスト発行
した場合の値をプロットしました．

mod_uploader は Perl の約 100 倍，PHP の約 10 倍高速に動作しています．
これらの言語を使った場合， `mod_perl`_ （ModPerl::Registry）や `APC`_
を使用すればある程度速度を改善することが可能です．それでも，
mod_uploader には及びません．

.. 補足：
.. 
.. なんか，使用言語がパフォーマンスのキーになるような書き方になってます
.. が，もちろん，言語よりも他の要素に負うところの方が大きいです．
.. mod_perl や APC 使っていればなおさらです．
..
.. アジテーションが目的の文章ですんで，軽く読み流して頂けると幸いです．
.. (やっぱりダメ？)

また，mod_uploader は，静的な HTML を用いるものと比べてもわずかながら高
速に動作します．これは，表示に静的な HTML を用いる場合でも，アップロー
ド処理のためには libphp4.so をロードする必要があるので，そのためのオー
バーヘッドがかかっているのが原因と思われます．libphp4.so のロードを無く
した場合，HTML の値は 2,800 を超えて最速になります．

省メモリのアップロード
```````````````````````````````````````````````````````````````````````

mod_uploader は，巨大なファイルのアップロードにもわずかなメモリしか消費
しません．

それに対してアップローダの多くは，アップロードされたデータを一旦全てメ
モリに入れて処理するため，アップロードにはファイルサイズに比例したサイ
ズのメモリを消費してしまいます．

.. 補足：
.. 
.. サイズが小さいファイルをアップロードするだけだったら，全部メモリに読
.. み込んで処理するのは良い選択だと思います．でも，数十メガバイト以上の
.. サイズを扱うには無理があります．


テスト結果
----------------------------------------------------------------------

`テスト結果一覧 <http://acapulco.dyndns.org/mod_uploader/status/>`_


API ドキュメント
----------------------------------------------------------------------

http://acapulco.dyndns.org/mod_uploader/api/


参考文献
----------------------------------------------------------------------

プログラムの作成にあたってお世話になった文献を紹介します．

|Panda|_ |Secure|_

`Apacheモジュール プログラミングガイド`_
  `Apache`_ のモジュール作成に必要になる事柄を一通り説明した本．痒いと
  ころに手が届いているので，手元に置いておくと重宝します．

`Secure Coding in C And C++`_
  C/C++ でプログラムを作るときにセキュリティホールが発生してしまう原理と
  その対策について詳しく説明した本です．丁寧に書かれているので内容を
  しっかりと理解することができます．

`Advanced Topics in Module Design: Threadsafety and Portability`_
  `Apache`_ 2.0 でモジュールを作成するときに必要になってくるテクニック
  が解説されたパワポ．そんなに長くないので，モジュール書く前にさらっと
  読んでおきましょう．

`Apache API C++ Cookbook`_
  C++ を使って `Apache`_ のモジュールを作成する際の注意事項について説明
  したサイト．

`libapr (apache portable runtime) programming tutorial`_
  APR のチュートリアル．サンプルコードおよび，間違いやすい点についての
  記述が多いので重宝します．

`Using libavformat and libavcodec: An Update`_
  libavformat と libavcodec を使って動画からフレーム画像を取り出す方法
  を解説したページ．丁寧に書かれています．

`STL のページ`_
  C++ の標準テンプレートライブラリである STL について簡潔にまとめられた
  サイト．

`RubyExtensionProgrammingGuide`_
  Ruby の拡張ライブラリの書き方を解説したサイト．基本的な事項から少し高
  度な話題まで非常に良くまとまってます．

`Compiler Construction Lecture`_
  コンパイラ作成に関する実践的な内容が簡潔にまとめられたサイト．簡単な
  インタプリタもどきを作るんだったら，このサイトだけで十分かも．

.. _`Microsoft Windows`:              http://www.microsoft.com/japan/windows/
.. _`Apache`:                         http://httpd.apache.org/
.. _`Intel C++ Compiler`:             http://www.intel.com/cd/software/products/asmo-na/eng/compilers/clin/
.. _`.NET Framework`:                 http://www.microsoft.com/japan/msdn/netframework/
.. _`GNU Make`:                       http://www.gnu.org/software/make/
.. _`ImageMagick`:                    http://www.imagemagick.org/
.. _`Visual C++ .NET`:                http://www.microsoft.com/japan/msdn/visualc/
.. _`Cygwin`:                         http://www.cygwin.com/
.. _`The zlib/libpng License`:        http://www.opensource.org/licenses/zlib-license.php
.. _`The zlib/libpng License の翻訳`: http://japan.linux.com/docs/licenses/zlib-license.shtml
.. _`Gentoo Linux`:                   http://www.gentoo.org/
.. _`FreeBSD`:                        http://www.freebsd.org/
.. _`Mac OSX Tiger`:                  http://www.apple.com/macosx/
.. _`mod_perl`:                       http://perl.apache.org/
.. _`APC`:                            http://pecl.php.net/package/APC/
.. _`Valgrind`:                       http://valgrind.org/

.. _`Apacheモジュール プログラミングガイド`: http://www.amazon.co.jp/exec/obidos/ASIN/4774117994/cstation-22
.. _`Secure Coding in C And C++`: http://www.amazon.co.jp/exec/obidos/ASIN/0321335724/cstation-22
.. _`Advanced Topics in Module Design: Threadsafety and Portability`: http://www.clove.org/~aaron/presentations/apachecon2004/ac2004advancedmodules.ppt
.. _`Apache API C++ Cookbook`:       http://zach.chambana.net/apache-cplusplus/ 
.. _`libapr (apache portable runtime) programming tutorial`: http://dev.ariel-networks.com/apr/apr-tutorial/html/apr-tutorial.html             
.. _`Using libavformat and libavcodec: An Update`: http://www.inb.uni-luebeck.de/~boehme/libavcodec_update.html
.. _`STL のページ`:                   http://www.wakhok.ac.jp/~sumi/stl/
.. _`RubyExtensionProgrammingGuide`:  http://i.loveruby.net/w/RubyExtensionProgrammingGuide.html
.. _`Compiler Construction Lecture`:  http://rananim.ie.u-ryukyu.ac.jp/~kono/lecture/compiler/

.. |Panda| image:: img/panda.png
   :width: 120
   :height: 151
   :alt: Apacheモジュール プログラミングガイド
   :align: right
.. _`Panda`: http://www.amazon.co.jp/exec/obidos/ASIN/4774117994/cstation-22

.. |Secure| image:: img/secure.png
   :width: 120
   :height: 151
   :alt: Secure Coding in C And C++
   :align: right
.. _`Secure`: http://www.amazon.co.jp/exec/obidos/ASIN/0321335724/cstation-22

.. raw:: html

  <hr />

  <div class="footer">
   <p class="id">
    $Id: apache.txt 1248 2006-08-05 05:51:43Z svn $
   </p>

   <address>
    <img src="img/mail_address.png" width="204" height="16" alt="&#107;&#105;&#109;&#97;&#116;&#97;&#64;&#97;&#99;&#97;&#112;&#117;&#108;&#99;&#111;&#46;&#100;&#121;&#110;&#100;&#110;&#115;&#46;&#111;&#114;&#103;" />
   </address>

   <p class="validator">
    <a href="http://validator.w3.org/check?uri=referer">
     <img src="http://www.w3.org/Icons/valid-xhtml11" alt="Valid XHTML 1.1!" height="31" width="88" />
    </a>
    <a href="http://jigsaw.w3.org/css-validator/check/referer">
     <img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
    </a>
   </p>
  </div>

.. Local Variables:
.. mode: rst
.. buffer-file-coding-system: utf-8-unix
.. End:

