You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2012/12/03 14:33:18 UTC
[2/33] git commit: Add Sphinx-related build changes into READMEs
Add Sphinx-related build changes into READMEs
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/86be5a68
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/86be5a68
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/86be5a68
Branch: refs/heads/1536-feature_add-docs
Commit: 86be5a6897ec71d1c556668b71ee9b3e4fcc618e
Parents: 392723c
Author: Noah Slater <ns...@apache.org>
Authored: Mon Dec 3 10:04:54 2012 +0100
Committer: Dave Cottlehuber <dc...@apache.org>
Committed: Mon Dec 3 14:17:07 2012 +0100
----------------------------------------------------------------------
AUTHORS | 1 -
BUGS | 6 ++-
DEVELOPERS | 114 ++++++++++++++++++++++++++++++++++++++++++-------
INSTALL.Unix | 55 +++++++++++++++++-------
INSTALL.Windows | 36 ++++++++++-----
LICENSE | 115 ++++++++++++++++++++++++++++++++++++++++++++++----
NOTICE | 28 ++++++------
README | 4 ++
8 files changed, 289 insertions(+), 70 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/AUTHORS
----------------------------------------------------------------------
diff --git a/AUTHORS b/AUTHORS
index e55c0b0..49b5ef1 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -21,5 +21,4 @@ documentation or developing software. Some of these people are:
* Dave Cottlehuber <dc...@apache.org>
* Jason Smith <jh...@apache.org>
-
For a list of other credits see the `THANKS` file.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/BUGS
----------------------------------------------------------------------
diff --git a/BUGS b/BUGS
index 8cd1d16..1bdc478 100644
--- a/BUGS
+++ b/BUGS
@@ -1,6 +1,8 @@
Apache CouchDB BUGS
===================
-Please see the [documentation][1] on how to report bugs with Apache CouchDB.
+Visit our issue tracker:
-[1] http://couchdb.apache.org/community/issues.html
+ https://issues.apache.org/jira/browse/CouchDB
+
+You can use this to report bugs, request features, or suggest enhancements.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/DEVELOPERS
----------------------------------------------------------------------
diff --git a/DEVELOPERS b/DEVELOPERS
index 84976d7..f61b77b 100644
--- a/DEVELOPERS
+++ b/DEVELOPERS
@@ -10,30 +10,95 @@ Dependencies
You will need the following installed:
- * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/)
- * GNU Autoconf (>=2.59) (http://www.gnu.org/software/autoconf/)
* GNU Libtool (http://www.gnu.org/software/libtool/)
+ * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/)
+ * GNU Autoconf (>=2.68) (http://www.gnu.org/software/autoconf/)
+ * GNU Autoconf Archive (http://www.gnu.org/software/autoconf-archive/)
+ * pkg-config (http://www.freedesktop.org/wiki/Software/pkg-config)
+
+You may also need:
+
+ * Sphinx (http://sphinx.pocoo.org/)
+ * LaTex (http://www.latex-project.org/)
+ * GNU Texinfo (http://www.gnu.org/software/texinfo/)
* GNU help2man (http://www.gnu.org/software/help2man/)
-The `help2man` tool is optional, but will generate `man` pages for you.
+These optional dependencies are required for building the documentation.
+
+You will need these optional dependencies installed if:
+
+ * You are preparing a distribution archive
+
+However, you do not need them if:
+
+ * You are building from a distribution archive, or
+ * You don't care about building the documentation
Debian-based (inc. Ubuntu) Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can install the dependencies by running:
+You can install the required dependencies by running:
+
+ sudo apt-get install libtool
+ sudo apt-get install automake
+ sudo apt-get install autoconf
+ sudo apt-get install autoconf-archive
+ sudo apt-get install pkg-config
- apt-get install automake autoconf libtool help2man
+Optional dependencies:
+
+ sudo apt-get install help2man
+ sudo apt-get install python-sphinx
+ sudo apt-get install texlive-latex-base
+ sudo apt-get install texlive-latex-recommended
+ sudo apt-get install texlive-latex-extra
+ sudo apt-get install texlive-fonts-recommended
+ sudo apt-get install texinfo
Be sure to update the version numbers to match your system's available packages.
Mac OS X
~~~~~~~~
-You can install the dependencies by running:
+Install Homebrew, if you do not have it already:
+
+ https://github.com/mxcl/homebrew
+
+You can install the required dependencies by running:
+
+ brew install libtool
+ brew install automake
+ brew install autoconf
+ brew install autoconf-archive
+ brew install pkg-config
+
+Unless you want to install the optional dependencies, skip to the next section.
- port install automake autoconf libtool help2man
+Install what else we can with Homebrew:
-You will need MacPorts installed to use the `port` command.
+ brew install help2man
+
+If you don't already have pip installed, install it:
+
+ sudo easy_install pip
+
+Now, install the required Python packages:
+
+ sudo pip install sphinx
+ sudo pip install docutils
+ sudo pip install pygments
+
+Download MaxTeX from here:
+
+ http://www.tug.org/mactex/
+
+Follow the instructions to get a working LaTeX install on your system.
+
+Windows
+~~~~~~~
+
+ Follow the instructions in INSTALL.Windows and build all components
+ from source, using the same Visual C++ compiler and runtime.
Bootstrapping
-------------
@@ -44,6 +109,29 @@ Bootstrap the pristine source by running:
You must repeat this step every time you update your source checkout.
+Configuring
+-----------
+
+Configure the source by running:
+
+ ./configure
+
+Note that this will not fail when the optional dependencies are missing.
+
+To ensure the optional dependencies are installed, run:
+
+ ./configure --enable-strictness
+
+If you don't care about docs and want to skip the whole thing, run:
+
+ ./configure --disable-docs
+
+If you're working on the build system itself, you can run:
+
+ ./configure --disable-tests
+
+This skips the tests allowing quicker `make' cycles.
+
Testing
-------
@@ -60,17 +148,13 @@ Please report any problems to the developer's mailing list.
Releasing
---------
-The release procedure is documented in the project wiki:
+The release procedure is documented here:
https://wiki.apache.org/couchdb/Release_procedure
Unix-like Systems
~~~~~~~~~~~~~~~~~
-Configure the source by running:
-
- ./configure
-
Prepare the release artefacts by running:
make distcheck
@@ -84,10 +168,6 @@ The release artefacts can be found in the root source directory.
Microsoft Windows
~~~~~~~~~~~~~~~~~
-Configure the source by running:
-
- ./configure
-
Prepare the release artefacts by running:
make dist
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/INSTALL.Unix
----------------------------------------------------------------------
diff --git a/INSTALL.Unix b/INSTALL.Unix
index baf9d06..3e9dce5 100644
--- a/INSTALL.Unix
+++ b/INSTALL.Unix
@@ -3,6 +3,16 @@ Apache CouchDB README.Unix
A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
+Community installation guides are available on the wiki:
+
+ http://wiki.apache.org/couchdb/Installation
+
+This document is the canonical source of installation information. However, many
+systems have gotchas that you need to be aware of. In addition, dependencies
+frequently change as distributions update their archives. If you're running into
+trouble, be sure to check out the wiki. If you have any tips to share, please
+also update the wiki so that others can benefit from your experience.
+
Troubleshooting
---------------
@@ -33,32 +43,42 @@ You should have the following installed:
* GNU Compiler Collection (http://gcc.gnu.org/)
* libcurl (http://curl.haxx.se/libcurl/)
* help2man (http://www.gnu.org/s/help2man/)
+ * Python (>= 2.7) for docs (http://python.org/)
+ * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx)
-It is recommended that you install Erlang OTP R12B-5 or above where possible.
-You will only need libcurl if you plan to run the JavaScript test suite. And
+It is recommended that you install Erlang OTP R13B04 or above where possible.
+You will only need libcurl if you plan to run the JavaScript test suite.
help2man is only need if you plan on installing the CouchDB man pages.
-
-Ubuntu
-~~~~~~
-
-For up to date instructions, please see:
-
- http://wiki.apache.org/couchdb/Installing_on_Ubuntu
-
-Unfortunately, it seems that installing dependancies on Ubuntu is troublesome.
+Python and Sphinx are only required for building the online documentation.
Debian-based Systems
~~~~~~~~~~~~~~~~~~~~
-You can install the build tools by running:
+You can install the dependencies by running:
sudo apt-get install build-essential
+ sudo apt-get install erlang-base-hipe
+ sudo apt-get install erlang-dev
+ sudo apt-get install erlang-manpages
+ sudo apt-get install erlang-eunit
+ sudo apt-get install erlang-nox
+ sudo apt-get install libicu-dev
+ sudo apt-get install libmozjs-dev
+ sudo apt-get install libcurl4-openssl-dev
+
+There are lots of Erlang packages. If there is a problem with your install, try
+a different mix. There is more information on the wiki. Additionally, you might
+want to install some of the optional Erlang tools which may also be useful.
-You can install the other dependencies by running:
+Be sure to update the version numbers to match your system's available packages.
+
+For up to date instructions, please see:
- sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev
+ http://wiki.apache.org/couchdb/Installing_on_Debian
-Be sure to update the version numbers to match your system's available packages.
+ http://wiki.apache.org/couchdb/Installing_on_Ubuntu
+
+Unfortunately, it seems that installing dependencies on Ubuntu is troublesome.
Mac OS X
~~~~~~~~
@@ -69,7 +89,10 @@ You can install the build tools by running:
You can install the other dependencies by running:
- brew install erlang icu4c spidermonkey curl
+ brew install erlang
+ brew install icu4c
+ brew install spidermonkey
+ brew install curl
You may want to link ICU so that CouchDB can find the header files automatically:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/INSTALL.Windows
----------------------------------------------------------------------
diff --git a/INSTALL.Windows b/INSTALL.Windows
index b75b80a..89ab231 100644
--- a/INSTALL.Windows
+++ b/INSTALL.Windows
@@ -14,6 +14,10 @@ There is a wiki for general documentation:
http://wiki.apache.org/couchdb/
+And some Windows-specific tips:
+
+ http://wiki.apache.org/couchdb/Quirks_on_Windows
+
There are collection of friendly mailing lists:
http://couchdb.apache.org/community/lists.html
@@ -25,28 +29,36 @@ Dependencies
You will need the following installed:
- * Erlang OTP (=14B01) (http://erlang.org/)
- * ICU (=4.4.*) (http://icu.sourceforge.net/)
- * OpenSSL (http://www.openssl.org/)
- * Mozilla SpiderMonkey (1.7) (http://www.mozilla.org/js/spidermonkey/)
- * libcurl (http://curl.haxx.se/libcurl/)
- * Cygwin (http://www.cygwin.com/)
- * Visual Studio 2008 (http://msdn.microsoft.com/en-gb/vstudio/default.aspx)
+ * Erlang OTP (>=14B01) (http://erlang.org/)
+ * ICU (>=4.*) (http://icu.sourceforge.net/)
+ * OpenSSL (>=0.9.8r) (http://www.openssl.org/)
+ * Mozilla SpiderMonkey (=1.8.5) (http://www.mozilla.org/js/spidermonkey/)
+ * libcurl (http://curl.haxx.se/libcurl/)
+ * Cygwin (http://www.cygwin.com/)
+ * Microsoft SDK 7.0 or 7.1 (http://www.microsoft.com/en-us/download/details.aspx?id=8279)
+ * Python (>= 2.7) for docs (http://python.org/)
+ * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx)
General Notes
-------------
+ * When installing Cygwin, be sure to select all the `development` tools.
+
* When installing Erlang, you must build it from source.
- The CouchDB build requires a number of the Erlang build scripts.
+ * The CouchDB build requires a number of the Erlang build scripts.
- * When installing ICU, select the binaries built with Visual Studio 2008.
+ * All dependent libraries should be built with the same version of
+ microsoft SDK.
- * When installing Cygwin, be sure to select all the `development` tools.
+ * Do not try to link against libraries built with, or included in,
+ Cygwin or MingW. They are not compatible with the Erlang/OTP or CouchDB
+ build scripts.
- * When installing libcurl, be sure to install by hand.
+ * ICU version 4.6 and later will build cleanly using MSBuild.
- The Cygwin binaries are incompatible and will not work with Erlang.
+ * Python and Sphinx are only required for building the online documentation.
+ Use cygwin-provided Python and install Sphinx via easy_install or pip.
Setting Up Cygwin
-----------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/LICENSE
----------------------------------------------------------------------
diff --git a/LICENSE b/LICENSE
index be511b1..be2404d 100644
--- a/LICENSE
+++ b/LICENSE
@@ -201,20 +201,120 @@
See the License for the specific language governing permissions and
limitations under the License.
-
Apache CouchDB Subcomponents
The Apache CouchDB project includes a number of subcomponents with separate
copyright notices and license terms. Your use of the code for the these
subcomponents is subject to the terms and conditions of the following licenses.
-For the m4/ac_check_icu.m4 component:
+For the share/doc/build/html/_static components:
+
+ Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+For the share/doc/build/html/_static/jquery.js component:
+
+ Copyright 2010, John Resig
+
+ Copyright 2010, The Dojo Foundation
+
+ Copyright 2012 jQuery Foundation and other contributors
+ http://jquery.com/
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For the share/doc/build/html/_static/underscore.js component:
+
+ Copyright (c) 2009-2012 Jeremy Ashkenas, DocumentCloud
- Copyright (c) 2005 Akos Maroy <da...@tyrell.hu>
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.
+
+For the share/doc/static/rtd.css components:
+
+ Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
- Copying and distribution of this file, with or without modification, are
- permitted in any medium without royalty provided the copyright notice
- and this notice are preserved.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
For the share/www/script/jquery.js component:
@@ -239,8 +339,7 @@ For the share/www/script/jquery.js component:
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-For the share/www/script/jquery-ui-1.8.11.custom.min.js and
- share/www/style/jquery-ui-1.8.11.custom.css components:
+For the share/www/script/jquery-ui-* components:
Copyright (c) 2011 Paul Bakaus, http://jqueryui.com/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index ef3ff9e..e627b92 100644
--- a/NOTICE
+++ b/NOTICE
@@ -6,18 +6,6 @@ The Apache Software Foundation (http://www.apache.org/).
This product also includes the following third-party components:
- * ac_check_icu.m4 (http://autoconf-archive.cryp.to/ac_check_icu.html)
-
- Copyright 2008, Akos Maroy <da...@tyrell.hu>
-
- * ac_check_curl.m4 (http://autoconf-archive.cryp.to/ac_check_curl.html)
-
- Copyright 2008, Akos Maroy <da...@tyrell.hu>
-
- * pkg.m4 (http://http://pkg-config.freedesktop.org/wiki/)
-
- Copyright 2004, Scott James Remnant <sc...@netsplit.com>
-
* jQuery (http://jquery.com/)
Copyright 2011, John Resig
@@ -28,7 +16,7 @@ This product also includes the following third-party components:
* json2.js (http://www.json.org/)
- In the public domain
+ Public domain
* MochiWeb (http://code.google.com/p/mochiweb/)
@@ -64,7 +52,7 @@ This product also includes the following third-party components:
* snappy (http://code.google.com/p/snappy/)
- Copyright 2005 and onwards Google Inc.
+ Copyright 2005, Google Inc.
* snappy-erlang-nif (https://github.com/fdmanana/snappy-erlang-nif)
@@ -73,3 +61,15 @@ This product also includes the following third-party components:
* CoffeeScript (http://coffeescript.org/)
Copyright 2011, Jeremy Ashkenas
+
+ * Sphinx (http://sphinx-doc.org/)
+
+ Copyright 2011, the Sphinx team
+
+ * Sizzle (http://sizzlejs.com/)
+
+ Copyright 2010, The Dojo Foundation
+
+ * Underscore.js 1.4.2 (http://underscorejs.org)
+
+ Copyright 2012, Jeremy Ashkenas
http://git-wip-us.apache.org/repos/asf/couchdb/blob/86be5a68/README
----------------------------------------------------------------------
diff --git a/README b/README
index 0d125fb..33b854d 100644
--- a/README
+++ b/README
@@ -34,6 +34,10 @@ If you're getting a cryptic error message, see:
For general help, see:
http://couchdb.apache.org/#mailing-list
+
+We also have an IRC channel:
+
+ http://webchat.freenode.net/?channels=couchdb
The mailing lists provide a wealth of support and knowledge for you to tap into.
Feel free to drop by with your questions or discussion. See the official CouchDB