couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From beno...@apache.org
Subject git commit: updated refs/heads/1988-move-my_first_plugin-to-examples to f184c53
Date Sun, 05 Jan 2014 08:21:52 GMT
Updated Branches:
  refs/heads/1988-move-my_first_plugin-to-examples [created] f184c536d


move couchdb plugin example to share/examples

fix #couchdb-1988


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/f184c536
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/f184c536
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/f184c536

Branch: refs/heads/1988-move-my_first_plugin-to-examples
Commit: f184c536dc9032dc1b1fbb081d1e790e8697925c
Parents: 9068db2
Author: Benoit Chesneau <benoitc@apache.org>
Authored: Sun Jan 5 09:21:01 2014 +0100
Committer: Benoit Chesneau <benoitc@apache.org>
Committed: Sun Jan 5 09:21:01 2014 +0100

----------------------------------------------------------------------
 configure.ac                                    |   3 +-
 license.skip                                    |  10 +-
 share/Makefile.am                               |   2 +-
 share/examples/Makefile.am                      |  22 +++
 .../examples/my-first-couchdb-plugin/README.md  | 196 +++++++++++++++++++
 .../priv/default.d/my_first_couchdb_plugin.ini  |   0
 .../src/my_first_couchdb_plugin.app.src         |  21 ++
 .../src/my_first_couchdb_plugin.erl             |  18 ++
 .../test/my_first_couchdb_plugin_tests.erl      |  15 ++
 src/Makefile.am                                 |  13 +-
 src/my-first-couchdb-plugin/.gitignore          |   1 -
 src/my-first-couchdb-plugin/Makefile            |  38 ----
 src/my-first-couchdb-plugin/README.md           | 196 -------------------
 .../priv/default.d/my_first_couchdb_plugin.ini  |   0
 .../src/my_first_couchdb_plugin.app.src         |  21 --
 .../src/my_first_couchdb_plugin.erl             |  18 --
 .../test/my_first_couchdb_plugin_tests.erl      |  15 --
 17 files changed, 281 insertions(+), 308 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/configure.ac
----------------------------------------------------------------------
diff --git a/configure.ac b/configure.ac
index 6c5ef5b..1f2dce7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -24,7 +24,7 @@ AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_HEADERS([src/snappy/google-snappy/config.h])
 
-AM_INIT_AUTOMAKE([1.6.3 foreign])
+AM_INIT_AUTOMAKE([1.6.3 foreign tar-ustar])
 
 AC_USE_SYSTEM_EXTENSIONS
 AC_ENABLE_SHARED
@@ -730,6 +730,7 @@ AC_CONFIG_FILES([etc/Makefile])
 AC_CONFIG_FILES([share/Makefile])
 AC_CONFIG_FILES([share/doc/Makefile])
 AC_CONFIG_FILES([share/doc/build/Makefile])
+AC_CONFIG_FILES([share/examples/Makefile])
 AC_CONFIG_FILES([src/Makefile])
 AC_CONFIG_FILES([src/couch_dbupdates/Makefile])
 AC_CONFIG_FILES([src/couch_index/Makefile])

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/license.skip
----------------------------------------------------------------------
diff --git a/license.skip b/license.skip
index 0895cf8..800957d 100644
--- a/license.skip
+++ b/license.skip
@@ -68,6 +68,11 @@
 ^share/doc/src/conf.pyc
 ^share/doc/static/rtd.css
 ^share/doc/templates/couchdb/domainindex.html
+^share/examples/my-first-couchdb-plugin/priv/*/*
+^share/examples/my-first-couchdb-plugin/README.md
+^share/examples/my-first-couchdb-plugin/.gitignore
+^share/examples/my-first-couchdb-plugin/Makefile
+^share/examples/my-first-couchdb-plugin/Makefile.in
 ^share/server/json2.js
 ^share/server/mimeparse.js
 ^share/server/coffee-script.js
@@ -154,11 +159,6 @@
 ^src/fauxton/assets/lib/ace/.*
 ^src/ibrowse/.*
 ^src/mochiweb/.*
-^src/my-first-couchdb-plugin/priv/*/*
-^src/my-first-couchdb-plugin/README.md
-^src/my-first-couchdb-plugin/.gitignore
-^src/my-first-couchdb-plugin/Makefile
-^src/my-first-couchdb-plugin/Makefile.in
 ^src/snappy/.*
 ^stamp-h1
 ^test/Makefile

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/Makefile.am
----------------------------------------------------------------------
diff --git a/share/Makefile.am b/share/Makefile.am
index 84b91cb..8c03ba4 100644
--- a/share/Makefile.am
+++ b/share/Makefile.am
@@ -10,7 +10,7 @@
 ## License for the specific language governing permissions and limitations under
 ## the License.
 
-SUBDIRS = doc
+SUBDIRS = doc examples
 
 JS_FILE = server/main.js
 

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/Makefile.am
----------------------------------------------------------------------
diff --git a/share/examples/Makefile.am b/share/examples/Makefile.am
new file mode 100644
index 0000000..e947028
--- /dev/null
+++ b/share/examples/Makefile.am
@@ -0,0 +1,22 @@
+## Licensed under the Apache License, Version 2.0 (the "License"); you may not
+## use this file except in compliance with the License. You may obtain a copy of
+## the License at
+##
+##   http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+## License for the specific language governing permissions and limitations under
+## the License.
+
+EXTRA_DIST = $(MY_FIRST_COUCHDB_PLUGIN_FILES)
+
+MY_FIRST_COUCHDB_PLUGIN_FILES = \
+  my-first-couchdb-plugin/.gitignore \
+  my-first-couchdb-plugin/Makefile \
+  my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini \
+  my-first-couchdb-plugin/README.md \
+  my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src \
+  my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl \
+  my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/my-first-couchdb-plugin/README.md
----------------------------------------------------------------------
diff --git a/share/examples/my-first-couchdb-plugin/README.md b/share/examples/my-first-couchdb-plugin/README.md
new file mode 100644
index 0000000..814ef3b
--- /dev/null
+++ b/share/examples/my-first-couchdb-plugin/README.md
@@ -0,0 +1,196 @@
+# My First CouchDB Plugin
+
+A practical guide to developing CouchDB plugins.
+
+*NOTE: This is incomplete, barely tested, works only with the 1867-feature-plugin branch
of Apache CouchDB and expects that you understand some Erlang. This is mostly for early review,
but if you are daring, you can learn someting already :)*
+
+
+## Preparation
+
+To get started, you need to install CouchDB from source, grab the CouchDB sources:
+
+    git clone https://git-wip-us.apache.org/repos/asf/couchdb.git
+    cd couchdb
+    git checkout -b 1867-feature-plugin origin/1867-feature-plugins
+
+Follow the instructions in `couchdb/INSTALL.Unix` and `couchdb/DEVELOPERS` to get a development
environment going.
+
+Be sure to install CouchDB into your system. If you want to install CouchDB into a development
directory, make sure that the `bin/` folder of that directory is in your `PATH`.
+
+Next, install *rebar* from <https://github.com/rebar/rebar>. Rebar is a build tool
for Erlang projects and it makes our lives a lot easier.
+
+
+## Quick Start
+
+
+`my_first_couchdb_plugin` includes two directories `src` and `test` with an `.erl` file in
them each. `src/my_first_couchdb_plugin.erl` is where our module code will live and `test/my_first_couchdb_plugin_tests.erl`
will contain any tests for that code.
+
+`src/my_first_couchdb_plugin.erl` now should look like this:
+
+    -module(my_first_couchdb_plugin).
+
+    -export([my_func/0]).
+
+    my_func() ->
+        ok.
+
+It doesn’t do much, but you get your first module going. Let’s try to compile it.
+
+`my_first_couchdb_plugin` comes with a `Makefile` that helps you with common tasks.
+
+To compile your code, simply run:
+
+    make
+
+The output should be something like this:
+
+    rebar compile
+    ==> my_first_couchdb_plugin (compile)
+    Compiled src/my_first_couchdb_plugin.erl
+
+The compiled results are stored in a directory called `ebin/`. Poke around in there if you
are interested on how this all looks.
+
+To run CouchDB with your new plugin make sure CouchDB isn’t already running elsewhere and
then do this:
+
+    make dev
+
+The output should look something like this:
+
+
+    Erlang R15B03 (erts-5.9.3.1) [source] [64-bit] [smp:4:4] [async-threads:4] [hipe] [kernel-poll:true]
[dtrace]
+
+    Eshell V5.9.3.1  (abort with ^G)
+    1> Apache CouchDB 1.3.0 (LogLevel=info) is starting.
+    Apache CouchDB has started. Time to relax.
+    [info] [<0.36.0>] Apache CouchDB has started on http://127.0.0.1:5984/
+
+That means, CouchDB is now running normally, in the foreground as opposed to in the background
like you would normally, so you get status and error messages in the terminal. And one more
thing, this drops you into an interactive Erlang shell that runs inside your CouchDB instance.
To see it, just hit enter and you will get:
+
+    1>
+
+This is the Erlang command prompt and you can enter arbitrary commands. To call our module
function, type this:
+
+    my_first_couchdb_plugin:my_func().
+
+And then enter. The full stop at the end is essential. The output should look like this:
+
+    1> my_first_couchdb_plugin:my_func().
+    ok
+    2>
+
+`ok` is the return value of your function, if you remember the code of `my_first_couchdb_plugin,erl`,
you see `ok` is the last statement before the final full stop in the function definition of
`my_func()` and thus, it is the return value of that function and we see it in the command
prompt. Then the command prompt waits for your next line of input with `2>` (the number
increases with each entered command). To get out of the command prompt and to stop CouchDB,
just hit `ctrl-c` twice.
+
+Note: from now on you can just type `make dev`, it will run `make` for you internally and
compile all changes you may have made in the meantime.
+
+* * *
+
+That is all that is needed to get started building a CouchDB plugin. The rest of this guide
will explain how to hook into the various parts of CouchDB that allow you to do all sorts
of fun things. That means you can write different types of plugins, once that handle HTTP
requests, others that operate on database changes, and yet others that provide a deamon that
does useful things for us.
+
+* * *
+
+
+## Publishing a Plugin
+
+Publishing a plugin is both simple and not so simple. The mechanics are trivial, just type:
+
+    make plugin
+
+and you will see something like this:
+
+    > make plugin
+    rebar compile
+    ==> my_first_couchdb_plugin (compile)
+    my_first_couchdb_plugin-1.0.0-R15B03-1.4.0.tar.gz: 1/MeXYfxeBK7DQyk10/6ucIRusc=
+
+That’s the easy part. The hard part is publishing the plugin. And since this is subject
to change a lot in the near future, we will punt on explaining this in detail here, but to
see how it works, look into this file in the CouchDB source distribution: `share/www/plugins.html`
+
+* * *
+
+
+## Creating an HTTP Handler
+
+Our module above is not very useful on its own. You can call it when you are in the Erlang
command prompt for your local CouchDB, but CouchDB itself doesn’t know what to do with it
and you can’t do anything with it from CouchDB’s HTTP API. Let’s fix that!
+
+CouchDB’s main API is HTTP and thus we can expect to have a lot of infrastructure to work
with. Luckily, it is mostly straigtforward to get into and we don’t need to learn a whole
lot before can get started, and learn more as we go along.
+
+Before ge get goint, let’s create another file that handles all our HTTP handler code.
Create `src/my_first_couchdb_plugin_httpd.erl` and put in the following contents:
+
+    -module(my_first_couchdb_plugin_httpd).
+
+    -export([handle_req/1]).
+
+    -include_lib("couch/include/couch_db.hrl").
+
+    handle_req(#httpd{method='GET'}=Req) ->
+        couch_httpd:send_json(Req, {[{<<"hello">>, <<"world">>}]});
+    handle_req(Req) ->
+        couch_httpd:send_method_not_allowed(Req, "GET").
+
+Let’s go through this line by line:
+
+1. We define the module name, nothing to see here, move along.
+3. We export the function `handle_req`, e.g. we make it available to other modules.
+5. We include the standard CouchDB header. That gives us access to the internal data structures.
+7. We define the function `handle_req`. In particular, we define a clause of that function
in a way that it gets invoked whenever CouchDB receives an HTTP `GET` request. It takes one
argument, `Req` and it it includes all HTTP request information. `Req` is an instance of the
record type `#httpd{}` that we will learn a lot more about in the future.
+8. We return a bit of JSON, the Erlang, or ejson, equivalent of `{"hello":"world"}`.
+9. We define the final, or default clause for the `handle_req` function. This is a default
for all `handle_req` functions and handles the case when an API endpoint was called with an
unsupported HTTP method, or path or other request parameters. In our case it will say that
our `handle_req` only ever will handle `GET` requests and if it ever sees anything else, a
standard “method not allowed” response will be generated for us.
+
+
+### Registering an HTTP Handler
+
+Now we have a function that can handle HTTP requests, but we haven’t told CouchDB yet,
for what API endpoint this should be called.
+
+To do this, we need to take a little detour into the CouchDB configuration system, as CouchDB’s
HTTP routing is fully dynamic and configurable at runtime.
+
+To get an idea, open this file in CouchDB source directory: `etc/couchdb/default.ini.tpl.in`,
don’t mind the triple file extensions, this is essentialy an `.ini` file. Now scroll down
to the section `[httpd_global_handlers]`. You will find a list of API endpoints with mapping
to the code in CouchDB that handles it. for example:
+
+    _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "%localdatadir%/www"}
+
+This means that `/_utils` is handled by the erlang module `couch_httpd_misc_handlers` and
its function `handle_utils_dir_req` and it takes one additinal argument that is the document
root for Futon.
+
+Another example:
+
+    _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
+
+This means that `/_all_dbs`, the API endpoint that allows you to list all databases in CouchDB
is handled by, again, `couch_httpd_misc_handlers` but this time its function `handle_all_dbs_req`,
which does not take an additional argument.
+
+Say we want to make our `handle_req` function answer under the enpoint `/_my_plugin` (you
want to start with an underscore here, as CouchDB will consider all other characters as real
database names), we would add something like this:
+
+    _my_plugin = {my_first_couchdb_plugin, handle_req}
+
+But don’t add that to `etc/couchdb/default.ini.tpl.in`! Instead, craete a new `.ini` file
in your plugin at `priv/default.d/my_first_couchdb_plugin.ini` with these contents:
+
+    [httpd_global_handlers]
+    _my_plugin = {my_first_couchdb_plugin_httpd, handle_req}
+    
+
+Don’t miss the new line at the end.
+
+Now run `make dev` again, and then open a second terminal:
+
+    curl http://127.0.0.1:5984/_my_plugin
+    {"hello":"world"}
+
+It worked, yay!
+
+When we do a `POST` request, that should fail:
+
+    curl -X POST http://127.0.0.1:5984/_my_plugin
+
+
+
+TODO:
+- show that POST fails as expected
+- exploring #httpd{} and how to react to different kinds of HTTP requests
+- hook up `handle_req` with `my_func`
+...
+* * *
+
+
+## Creating a Daemon
+
+TBD
+
+
+TODO:
+-  add “what can go wrong at this step”

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini
----------------------------------------------------------------------
diff --git a/share/examples/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini
b/share/examples/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini
new file mode 100644
index 0000000..e69de29

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
----------------------------------------------------------------------
diff --git a/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src b/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
new file mode 100644
index 0000000..9a24bf8
--- /dev/null
+++ b/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
@@ -0,0 +1,21 @@
+% Licensed under the Apache License, Version 2.0 (the "License"); you may not
+% use this file except in compliance with the License. You may obtain a copy of
+% the License at
+%
+%   http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+% License for the specific language governing permissions and limitations under
+% the License.
+
+%% -*- mode: erlang -*-
+{application, my_first_couchdb_plugin, [
+    {description, "My First CouchDB Plugin"},
+    {vsn, "0.0.0"},
+    {modules, []},
+    {registered, []},
+    {applications, [kernel, stdlib]},
+    {env, []}
+]}.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
----------------------------------------------------------------------
diff --git a/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl b/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
new file mode 100644
index 0000000..64d728c
--- /dev/null
+++ b/share/examples/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
@@ -0,0 +1,18 @@
+% Licensed under the Apache License, Version 2.0 (the "License"); you may not
+% use this file except in compliance with the License. You may obtain a copy of
+% the License at
+%
+%   http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+% License for the specific language governing permissions and limitations under
+% the License.
+
+-module(my_first_couchdb_plugin).
+
+-export([my_func/0]).
+
+my_func() ->
+    ok.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/share/examples/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
----------------------------------------------------------------------
diff --git a/share/examples/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
b/share/examples/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
new file mode 100644
index 0000000..53d75df
--- /dev/null
+++ b/share/examples/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
@@ -0,0 +1,15 @@
+% Licensed under the Apache License, Version 2.0 (the "License"); you may not
+% use this file except in compliance with the License. You may obtain a copy of
+% the License at
+%
+%   http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+% License for the specific language governing permissions and limitations under
+% the License.
+
+-module(my_first_couchdb_plugin_tests).
+-include_lib("eunit/include/eunit.hrl").
+

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/Makefile.am
----------------------------------------------------------------------
diff --git a/src/Makefile.am b/src/Makefile.am
index 378f82b..fc0e62d 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -25,18 +25,7 @@ SUBDIRS = \
     snappy \
     couchjs-node
 
-EXTRA_DIST = \
-    $(MY_FIRST_COUCHDB_PLUGIN_FILES) \
-    $(FAUXTON_FILES)
-
-MY_FIRST_COUCHDB_PLUGIN_FILES = \
-  my-first-couchdb-plugin/.gitignore \
-  my-first-couchdb-plugin/Makefile \
-  my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini \
-  my-first-couchdb-plugin/README.md \
-  my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src \
-  my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl \
-  my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
+EXTRA_DIST = $(FAUXTON_FILES)
 
 FAUXTON_FILES = \
     fauxton/app/addons/activetasks/assets/less/activetasks.less \

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/.gitignore
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/.gitignore b/src/my-first-couchdb-plugin/.gitignore
deleted file mode 100644
index cfb2329..0000000
--- a/src/my-first-couchdb-plugin/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-ebin

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/Makefile
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/Makefile b/src/my-first-couchdb-plugin/Makefile
deleted file mode 100644
index 7806bd7..0000000
--- a/src/my-first-couchdb-plugin/Makefile
+++ /dev/null
@@ -1,38 +0,0 @@
-## Licensed under the Apache License, Version 2.0 (the "License"); you may not
-## use this file except in compliance with the License. You may obtain a copy of
-## the License at
-##
-##   http://www.apache.org/licenses/LICENSE-2.0
-##
-## Unless required by applicable law or agreed to in writing, software
-## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-## License for the specific language governing permissions and limitations under
-## the License.
-
-# Customize here
-NAME=my_first_couchdb_plugin
-VERSION=1.0.0
-# Stop customizing here
-
-ERL=$(shell couch-config --erl-bin)
-ERLANG_VERSION=$(shell couch-config --erlang-version)
-COUCHDB_VERSION=$(shell couch-config --couch-version | sed 's/\+.*//')
-PLUGIN_DIRS=ebin priv
-PLUGIN_VERSION_SLUG=$(NAME)-$(VERSION)-$(ERLANG_VERSION)-$(COUCHDB_VERSION)
-PLUGIN_DIST=$(PLUGIN_VERSION_SLUG)
-
-all: compile
-
-compile:
-	ERL_LIBS=$(shell couch-config --erl-libs-dir):$(ERL_LIBS) rebar compile
-
-dev:
-	@ERL_LIBS=$(shell pwd) couchdb -i -a priv/default.d/*.ini
-
-plugin: compile
-	@mkdir -p $(PLUGIN_DIRS)
-	@mkdir -p $(PLUGIN_DIST)
-	@cp -r $(PLUGIN_DIRS) $(PLUGIN_DIST)
-	@tar czf $(PLUGIN_VERSION_SLUG).tar.gz $(PLUGIN_DIST)
-	@$(ERL) -eval 'File = "$(PLUGIN_VERSION_SLUG).tar.gz", {ok, Data} = file:read_file(File),io:format("~s:
~s~n", [File, base64:encode(crypto:sha(Data))]),halt()' -noshell

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/README.md
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/README.md b/src/my-first-couchdb-plugin/README.md
deleted file mode 100644
index 814ef3b..0000000
--- a/src/my-first-couchdb-plugin/README.md
+++ /dev/null
@@ -1,196 +0,0 @@
-# My First CouchDB Plugin
-
-A practical guide to developing CouchDB plugins.
-
-*NOTE: This is incomplete, barely tested, works only with the 1867-feature-plugin branch
of Apache CouchDB and expects that you understand some Erlang. This is mostly for early review,
but if you are daring, you can learn someting already :)*
-
-
-## Preparation
-
-To get started, you need to install CouchDB from source, grab the CouchDB sources:
-
-    git clone https://git-wip-us.apache.org/repos/asf/couchdb.git
-    cd couchdb
-    git checkout -b 1867-feature-plugin origin/1867-feature-plugins
-
-Follow the instructions in `couchdb/INSTALL.Unix` and `couchdb/DEVELOPERS` to get a development
environment going.
-
-Be sure to install CouchDB into your system. If you want to install CouchDB into a development
directory, make sure that the `bin/` folder of that directory is in your `PATH`.
-
-Next, install *rebar* from <https://github.com/rebar/rebar>. Rebar is a build tool
for Erlang projects and it makes our lives a lot easier.
-
-
-## Quick Start
-
-
-`my_first_couchdb_plugin` includes two directories `src` and `test` with an `.erl` file in
them each. `src/my_first_couchdb_plugin.erl` is where our module code will live and `test/my_first_couchdb_plugin_tests.erl`
will contain any tests for that code.
-
-`src/my_first_couchdb_plugin.erl` now should look like this:
-
-    -module(my_first_couchdb_plugin).
-
-    -export([my_func/0]).
-
-    my_func() ->
-        ok.
-
-It doesn’t do much, but you get your first module going. Let’s try to compile it.
-
-`my_first_couchdb_plugin` comes with a `Makefile` that helps you with common tasks.
-
-To compile your code, simply run:
-
-    make
-
-The output should be something like this:
-
-    rebar compile
-    ==> my_first_couchdb_plugin (compile)
-    Compiled src/my_first_couchdb_plugin.erl
-
-The compiled results are stored in a directory called `ebin/`. Poke around in there if you
are interested on how this all looks.
-
-To run CouchDB with your new plugin make sure CouchDB isn’t already running elsewhere and
then do this:
-
-    make dev
-
-The output should look something like this:
-
-
-    Erlang R15B03 (erts-5.9.3.1) [source] [64-bit] [smp:4:4] [async-threads:4] [hipe] [kernel-poll:true]
[dtrace]
-
-    Eshell V5.9.3.1  (abort with ^G)
-    1> Apache CouchDB 1.3.0 (LogLevel=info) is starting.
-    Apache CouchDB has started. Time to relax.
-    [info] [<0.36.0>] Apache CouchDB has started on http://127.0.0.1:5984/
-
-That means, CouchDB is now running normally, in the foreground as opposed to in the background
like you would normally, so you get status and error messages in the terminal. And one more
thing, this drops you into an interactive Erlang shell that runs inside your CouchDB instance.
To see it, just hit enter and you will get:
-
-    1>
-
-This is the Erlang command prompt and you can enter arbitrary commands. To call our module
function, type this:
-
-    my_first_couchdb_plugin:my_func().
-
-And then enter. The full stop at the end is essential. The output should look like this:
-
-    1> my_first_couchdb_plugin:my_func().
-    ok
-    2>
-
-`ok` is the return value of your function, if you remember the code of `my_first_couchdb_plugin,erl`,
you see `ok` is the last statement before the final full stop in the function definition of
`my_func()` and thus, it is the return value of that function and we see it in the command
prompt. Then the command prompt waits for your next line of input with `2>` (the number
increases with each entered command). To get out of the command prompt and to stop CouchDB,
just hit `ctrl-c` twice.
-
-Note: from now on you can just type `make dev`, it will run `make` for you internally and
compile all changes you may have made in the meantime.
-
-* * *
-
-That is all that is needed to get started building a CouchDB plugin. The rest of this guide
will explain how to hook into the various parts of CouchDB that allow you to do all sorts
of fun things. That means you can write different types of plugins, once that handle HTTP
requests, others that operate on database changes, and yet others that provide a deamon that
does useful things for us.
-
-* * *
-
-
-## Publishing a Plugin
-
-Publishing a plugin is both simple and not so simple. The mechanics are trivial, just type:
-
-    make plugin
-
-and you will see something like this:
-
-    > make plugin
-    rebar compile
-    ==> my_first_couchdb_plugin (compile)
-    my_first_couchdb_plugin-1.0.0-R15B03-1.4.0.tar.gz: 1/MeXYfxeBK7DQyk10/6ucIRusc=
-
-That’s the easy part. The hard part is publishing the plugin. And since this is subject
to change a lot in the near future, we will punt on explaining this in detail here, but to
see how it works, look into this file in the CouchDB source distribution: `share/www/plugins.html`
-
-* * *
-
-
-## Creating an HTTP Handler
-
-Our module above is not very useful on its own. You can call it when you are in the Erlang
command prompt for your local CouchDB, but CouchDB itself doesn’t know what to do with it
and you can’t do anything with it from CouchDB’s HTTP API. Let’s fix that!
-
-CouchDB’s main API is HTTP and thus we can expect to have a lot of infrastructure to work
with. Luckily, it is mostly straigtforward to get into and we don’t need to learn a whole
lot before can get started, and learn more as we go along.
-
-Before ge get goint, let’s create another file that handles all our HTTP handler code.
Create `src/my_first_couchdb_plugin_httpd.erl` and put in the following contents:
-
-    -module(my_first_couchdb_plugin_httpd).
-
-    -export([handle_req/1]).
-
-    -include_lib("couch/include/couch_db.hrl").
-
-    handle_req(#httpd{method='GET'}=Req) ->
-        couch_httpd:send_json(Req, {[{<<"hello">>, <<"world">>}]});
-    handle_req(Req) ->
-        couch_httpd:send_method_not_allowed(Req, "GET").
-
-Let’s go through this line by line:
-
-1. We define the module name, nothing to see here, move along.
-3. We export the function `handle_req`, e.g. we make it available to other modules.
-5. We include the standard CouchDB header. That gives us access to the internal data structures.
-7. We define the function `handle_req`. In particular, we define a clause of that function
in a way that it gets invoked whenever CouchDB receives an HTTP `GET` request. It takes one
argument, `Req` and it it includes all HTTP request information. `Req` is an instance of the
record type `#httpd{}` that we will learn a lot more about in the future.
-8. We return a bit of JSON, the Erlang, or ejson, equivalent of `{"hello":"world"}`.
-9. We define the final, or default clause for the `handle_req` function. This is a default
for all `handle_req` functions and handles the case when an API endpoint was called with an
unsupported HTTP method, or path or other request parameters. In our case it will say that
our `handle_req` only ever will handle `GET` requests and if it ever sees anything else, a
standard “method not allowed” response will be generated for us.
-
-
-### Registering an HTTP Handler
-
-Now we have a function that can handle HTTP requests, but we haven’t told CouchDB yet,
for what API endpoint this should be called.
-
-To do this, we need to take a little detour into the CouchDB configuration system, as CouchDB’s
HTTP routing is fully dynamic and configurable at runtime.
-
-To get an idea, open this file in CouchDB source directory: `etc/couchdb/default.ini.tpl.in`,
don’t mind the triple file extensions, this is essentialy an `.ini` file. Now scroll down
to the section `[httpd_global_handlers]`. You will find a list of API endpoints with mapping
to the code in CouchDB that handles it. for example:
-
-    _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "%localdatadir%/www"}
-
-This means that `/_utils` is handled by the erlang module `couch_httpd_misc_handlers` and
its function `handle_utils_dir_req` and it takes one additinal argument that is the document
root for Futon.
-
-Another example:
-
-    _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
-
-This means that `/_all_dbs`, the API endpoint that allows you to list all databases in CouchDB
is handled by, again, `couch_httpd_misc_handlers` but this time its function `handle_all_dbs_req`,
which does not take an additional argument.
-
-Say we want to make our `handle_req` function answer under the enpoint `/_my_plugin` (you
want to start with an underscore here, as CouchDB will consider all other characters as real
database names), we would add something like this:
-
-    _my_plugin = {my_first_couchdb_plugin, handle_req}
-
-But don’t add that to `etc/couchdb/default.ini.tpl.in`! Instead, craete a new `.ini` file
in your plugin at `priv/default.d/my_first_couchdb_plugin.ini` with these contents:
-
-    [httpd_global_handlers]
-    _my_plugin = {my_first_couchdb_plugin_httpd, handle_req}
-    
-
-Don’t miss the new line at the end.
-
-Now run `make dev` again, and then open a second terminal:
-
-    curl http://127.0.0.1:5984/_my_plugin
-    {"hello":"world"}
-
-It worked, yay!
-
-When we do a `POST` request, that should fail:
-
-    curl -X POST http://127.0.0.1:5984/_my_plugin
-
-
-
-TODO:
-- show that POST fails as expected
-- exploring #httpd{} and how to react to different kinds of HTTP requests
-- hook up `handle_req` with `my_func`
-...
-* * *
-
-
-## Creating a Daemon
-
-TBD
-
-
-TODO:
--  add “what can go wrong at this step”

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini b/src/my-first-couchdb-plugin/priv/default.d/my_first_couchdb_plugin.ini
deleted file mode 100644
index e69de29..0000000

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src b/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
deleted file mode 100644
index 9a24bf8..0000000
--- a/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.app.src
+++ /dev/null
@@ -1,21 +0,0 @@
-% Licensed under the Apache License, Version 2.0 (the "License"); you may not
-% use this file except in compliance with the License. You may obtain a copy of
-% the License at
-%
-%   http://www.apache.org/licenses/LICENSE-2.0
-%
-% Unless required by applicable law or agreed to in writing, software
-% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-% License for the specific language governing permissions and limitations under
-% the License.
-
-%% -*- mode: erlang -*-
-{application, my_first_couchdb_plugin, [
-    {description, "My First CouchDB Plugin"},
-    {vsn, "0.0.0"},
-    {modules, []},
-    {registered, []},
-    {applications, [kernel, stdlib]},
-    {env, []}
-]}.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl b/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
deleted file mode 100644
index 64d728c..0000000
--- a/src/my-first-couchdb-plugin/src/my_first_couchdb_plugin.erl
+++ /dev/null
@@ -1,18 +0,0 @@
-% Licensed under the Apache License, Version 2.0 (the "License"); you may not
-% use this file except in compliance with the License. You may obtain a copy of
-% the License at
-%
-%   http://www.apache.org/licenses/LICENSE-2.0
-%
-% Unless required by applicable law or agreed to in writing, software
-% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-% License for the specific language governing permissions and limitations under
-% the License.
-
--module(my_first_couchdb_plugin).
-
--export([my_func/0]).
-
-my_func() ->
-    ok.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/f184c536/src/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
----------------------------------------------------------------------
diff --git a/src/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl b/src/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
deleted file mode 100644
index 53d75df..0000000
--- a/src/my-first-couchdb-plugin/test/my_first_couchdb_plugin_tests.erl
+++ /dev/null
@@ -1,15 +0,0 @@
-% Licensed under the Apache License, Version 2.0 (the "License"); you may not
-% use this file except in compliance with the License. You may obtain a copy of
-% the License at
-%
-%   http://www.apache.org/licenses/LICENSE-2.0
-%
-% Unless required by applicable law or agreed to in writing, software
-% distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-% WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-% License for the specific language governing permissions and limitations under
-% the License.
-
--module(my_first_couchdb_plugin_tests).
--include_lib("eunit/include/eunit.hrl").
-


Mime
View raw message