couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "Contributing" by NoahSlater
Date Sat, 29 Mar 2008 20:33:54 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The following page has been changed by NoahSlater:
http://wiki.apache.org/couchdb/Contributing

The comment on the change is:
Copied from original CouchDB wiki

New page:
Fancy helping out? Want to get your feet wet with Erlang? Contribute to CouchDB!

''This document is out of date, although some of this still applies you should seek clarification
from the mailing list or IRC before starting work on anything.''

== Erlang ==

See http://erlang.org/ for more about Erlang. A quick "What's Erlang" is provided the [http://erlang.org/faq/faq.html#AEN9|by
FAQ].

== Erlang Application Design ==

Erlang applications typically share a similar design. While Erlang was developed, a lot of
"best-practices" were established. It is a good idea to follow them, if you want to benefit
from all of Erlang's (cool) features.

The Erlang VM makes creating of new threads extremely cheap CPU-time-wise. It also implements
highly efficient message passing between threads. It does a good job of distributing all threads
over all available CPUs and cores of a system and it can even distribute threads over a network
onto other machines.

Writing an Erlang program requires you to think a bit about the design of your program. You
need to think a bit where concurrency can (or ''should'') happen in your program. It is essential
to identify the parts that don't need tight coupling (of function calls and data structures).
You then create ''modules'' according to the parts of your system. Modules are a bit like
classes, in that they include all the interfaces, functions and data structures that are needed
for a specific task in your program, but they are not actually classes in the OO sense of
things. More on CouchDB's modules just in a bit.

Another significant concept in Erlang application design is the ignorance of error or exception
handling. In a function, you only care for cases you are interested in, not for possible problems
that can occur. If a function encounters something you didn't expect there, the thread running
the function simply gets terminated and the calling thread gets notified. Since a terminating
thread is usually not expected by the calling thread, it dies as well. This goes all back
the caller-chain to the original caller. This might sound weird at first, but it really helps
to keep code concise and maintainable.

Since Erlang is built to create server software, all the modules you create that do actual
work are supervised by a supervisor thread that makes sure the threads that work, are always
alive. If, in case of an error, a module terminates, the supervisor just respawns it.

=== CouchDB's Modules ===

CouchDB consists of a small set of modules to built up its functionality. To the outside,
CouchDB provides a REST interface via a HTTP server. There's obviously a module handling incoming
HTTP requests.

The HTTP server module then passes on requests to the ''couch'' module. The couch module looks
at the request and invokes the correct functions to serve it. A request could be asking for
a document in a database, the couch module then asks to the database module to get the data.
The database module checks, if document and database actually exist and then in turn asks
the storage module to actually read the data from disk.

CouchDB allows to create views on your data. If you query a view, the couch module asks the
view module to handle all the dirty work. The view module, in fact, is a standalone program
written in C and based on Mozilla !SpiderMonkey Engine that CouchDB just launches and talks
to view standard IO. Fabric is also managed by a supervisor thread as a daemon process in
your operating system.

Fulltext searching is realised very similar. It is handled by two independent daemons that
each take care of writing a search index and then querying that respectively.

== Help Wanted ==

Here's a short list of areas that can benefit from your help.

=== Security and Authentication ===

CouchDB currently lacks any security. We want to introduce a super-flexible permission system
with users and groups and read and write permissions that can be enforced on documents and
databases. @@ add more details

=== Database Partitioning ===

To handle vast amounts of data. Databases need to be partitioned over multiple servers. CouchDB
will make this super-easy for you, once you've implemented it. @@ add more details

=== Lucene ===

''Currently being worked on.''

The fulltext search implementation only does a bare minimum for now. You can improve that
by adding more flexible configuration options. For example, it'd be nice to be able to restrict
fulltext searching only to a specific field or set of fields in a document, or a restriction
based on a field value.

=== Sphinx ===

''Currently being worked on.''

Sphinx is a standalone full-text search engine, meant to provide fast, size-efficient and
relevant fulltext search functions to other applications. Right now it supports reading data
from MySQL, PostgreSQL, or XML. Hopefully CouchDB will be another possible data source soon.
Information on http://www.sphx.org @@ add more details

=== Xapian ===

''Currently being worked on.''

=== Unit Tests ===

We're looking to develop a build time unit test framework similar to the current tests available
at run time in the WWW admin console. Perhaps you have an idea how this might be implemented.

== Running CouchDB From the Source Directory ==

''This section is out of date though some parts may still apply.''

>>From the svn checkout directory, do the ''./bootstrap'', ''./configure'', and ''make''
steps. Then copy the config files to ''src/CouchDB''.

{{{
$ cp etc/couch.ini.dist src/CouchDB/couch.ini
$ cp etc/couch_httpd.conf.dist src/CouchDB/couch_httpd.conf
$ cp -r etc/conf src/CouchDB/
}}}

Edit ''couch.ini'' to point at the resources in your source checkout. Change the values of
''!DbRootDir'' and ''!LogFile'' to somewhere temporary. You may also wish to change the ''!LogLevel''
setting.

{{{
; etc/couch.ini.tpl.  Generated from couch.ini.tpl.in by configure.
...
DbRootDir=/home/matthew/sandbox/var/lib/couchdb

LogFile=/home/matthew/sandbox/var/log/couchdb/couch.log

HttpConfigFile=./couch_httpd.conf
..
[Couch Query Servers]

text/javascript=../../bin/couchjs -f ../../share/server/main.js
}}}

Edit ''couch_httpd.conf'' to set the document root and server root. Change ''!ErrorLog'' and
''!TransferLog'' to point somewhere temporary. If you also intend to run an install of CouchDB
that you aren't going to break early and often, change the value of ''Port''.

{{{
# etc/couch_httpd.conf.tpl.  Generated from couch_httpd.conf.tpl.in by configure.
...
DocumentRoot ../../share/www
ServerRoot ./
ErrorLog /home/matthew/sandbox/var/log/couchdb/http_error.log
TransferLog /home/matthew/sandbox/var/log/couchdb/http_access.log
...
}}}

Erlang needs to be aware of the modified ''inets'' library, so use the ''-pa'' flag to add
''couch_inets'' to the code path.

{{{
$ cd src/CouchDB
$ erl -pa ../couch_inets

Eshell V5.5.4  (abort with ^G)
1> couch_server:start().
couch 0.0.0 (LogLevel=info)
CouchDB is starting.
CouchDB has started. Time to relax.
{ok,<0.33.0>}
2>
}}}

To recompile an Erlang source file, while CouchDB runs, do ''c(erlang_module)''. So to recompile
the ''couch_server'' module with ''c(couch_server)''.

Mime
View raw message