Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

changing readme

  • Loading branch information...
commit e29e68062f6f88d35380cda8c53d6c4efcada85c 1 parent c7ed817
@guedes guedes authored
Showing with 115 additions and 39 deletions.
  1. +73 −21 README.md
  2. +42 −18 Rakefile
View
94 README.md
@@ -4,7 +4,7 @@ pgxn utils
What is it?
--------
-It aims to be a set of task to help PostgreSQL extension's developers to focus more on the problem that they wants to solve than in the structure and files and control files need to PGXS to build the extension.
+It is a set of task that help developers to create PostgreSQL's extensions, putting the extension's files in the recomended places and supplying tasks to help bundle and release your extension to PGXN.
How to install it?
------------------
@@ -17,7 +17,6 @@ Or you can install it by rubygems:
gem install pgxn_utils
-
How it works?
-------------
@@ -30,6 +29,7 @@ It is all about tasks. Let's see them:
pgxn-utils help [TASK] # Describe available tasks or one specific task
pgxn-utils release filename # Release an extension to PGXN
pgxn-utils skeleton extension_name # Creates an extension skeleton in current directory
+
# Creating a new extension
@@ -38,6 +38,7 @@ It is all about tasks. Let's see them:
create my_cool_extension
create my_cool_extension/my_cool_extension.control
create my_cool_extension/.gitignore
+ create my_cool_extension/.template
create my_cool_extension/META.json
create my_cool_extension/Makefile
create my_cool_extension/README.md
@@ -47,7 +48,12 @@ It is all about tasks. Let's see them:
create my_cool_extension/test/expected/base.out
create my_cool_extension/test/sql/base.sql
-You can start creating an extension with or without version control. By default `pgxn-utils`
+
+Thats it! Just start coding! ":)
+
+## Git support
+
+You can start a new extension with or without version control. By default `pgxn-utils`
supports [git](http://git-scm.org) but it will not create a repository unless you use `--git`
option in the skeleton task.
@@ -55,6 +61,7 @@ option in the skeleton task.
create my_cool_versioned_extension
create my_cool_versioned_extension/my_cool_versioned_extension.control
create my_cool_versioned_extension/.gitignore
+ create my_cool_versioned_extension/.template
create my_cool_versioned_extension/META.json
create my_cool_versioned_extension/Makefile
create my_cool_versioned_extension/README.md
@@ -66,16 +73,71 @@ option in the skeleton task.
init /tmp/my_cool_versioned_extension
commit initial commit
-Thats it! Just start coding! ":)
+
+
+When you create a new extension with git support in addition to create skeleton,
+`pgxn-utils` will initialize a git repository and create the initial commit.
+
+Once you have your extension in a git repository your `bundle` will use only the
+commited files to create the archive, but if your repository is dirty then `pgxn-utils`
+will hint you to commit or stash your changes, before bundle.
+
+You must be careful with new files not added to repository, because they will NOT
+be archived.
+
+## Default templates
+
+`pgxn-utils` has three templates: `sql`, `c` and `fdw`. If you call `skeleton` without
+specifying a template the `sql` is the default. But if your extension will supply some C
+modules or you will create a FDW, you can create the extension calling `skeleton` with a
+`--template` option.
+
+ $ pgxn-utils skeleton my_cool_c_extension --template=c
+ create my_cool_c_extension
+ create my_cool_c_extension/my_cool_c_extension.control
+ create my_cool_c_extension/.gitignore
+ create my_cool_c_extension/.template
+ create my_cool_c_extension/META.json
+ create my_cool_c_extension/Makefile
+ create my_cool_c_extension/README.md
+ create my_cool_c_extension/doc/my_cool_c_extension.md
+ create my_cool_c_extension/sql/my_cool_c_extension.sql
+ create my_cool_c_extension/sql/uninstall_my_cool_c_extension.sql
+ create my_cool_c_extension/src/my_cool_c_extension.c
+ create my_cool_c_extension/test/expected/base.out
+ create my_cool_c_extension/test/sql/base.sql
+
+
+
+ $ pgxn-utils skeleton my_cool_fdw_extension --template=fdw
+ create my_cool_fdw_extension
+ create my_cool_fdw_extension/my_cool_fdw_extension.control
+ create my_cool_fdw_extension/.gitignore
+ create my_cool_fdw_extension/.template
+ create my_cool_fdw_extension/META.json
+ create my_cool_fdw_extension/Makefile
+ create my_cool_fdw_extension/README.md
+ create my_cool_fdw_extension/doc/my_cool_fdw_extension.md
+ create my_cool_fdw_extension/sql/my_cool_fdw_extension.sql
+ create my_cool_fdw_extension/sql/uninstall_my_cool_fdw_extension.sql
+ create my_cool_fdw_extension/src/my_cool_fdw_extension_fdw.c
+ create my_cool_fdw_extension/test/expected/base.out
+ create my_cool_fdw_extension/test/sql/base.sql
+
+
+The templates contains examples codes and some links to PostgreSQL documentation
+that will try to help you to start coding. SQL and C templates contains some tests
+examples, and the example code will compiles and pass `make installcheck`, but they
+are examples and you must write your own tests and code.
# Changing something
-Well suppose you want to change the default maintainer's name and the license, well just do:
+Well suppose you want to change the default maintainer's name and the license, just do:
$ pgxn-utils change my_cool_extension --maintainer "Dickson Guedes" --license bsd
conflict META.json
Overwrite /tmp/my_cool_extension/META.json? (enter "h" for help) [Ynaqdh] d
- {
+ {
"name": "my_cool_extension",
"abstract": "A short description",
"description": "A long description",
@@ -108,7 +170,7 @@ Well suppose you want to change the default maintainer's name and the license, w
identical my_cool_extension.control
-It will wait you decide what to do.
+It will wait until you decide what to do.
For all switches that you can use with *change*, type:
@@ -134,8 +196,11 @@ For all switches that you can use with *change*, type:
# Bundling and Releasing!
Well, since you finished your work you can bundle it to send to [PGXN](http://pgxn.org).
+Note that if you have your extension in a git repository `bundle` will use only the
+commited files to create the archive, but if your repository is dirty then `pgxn-utils`
+will hint you to commit or stash your changes, before bundle.
-Bundle it:
+Let's bundle it:
$ pgxn-utils bundle my_cool_extension
create /home/guedes/extensions/my_cool_extension-0.0.1.zip
@@ -151,19 +216,6 @@ and release it:
You can export `PGXN_USER` and `PGXN_PASSWORD` environment variables to avoid
type username and password everytime.
-# Git support
-
-You can start a new extension with git support calling `skeleton` task with
-`--git` flag, then in addition to create skeleton, `pgxn-utils` will initialize
-a git repository and do a initial commit.
-
-Once you have your extension in a git repository your `bundle` will use only the
-commited files to create the archive, but if your repository is dirty then `pgxn-utils`
-will hint you to commit or stash your changes, before bundle.
-
-You must be careful with new files not added to repository, because they will NOT
-be archived.
-
# Working in progress
* improve [git](http://git-scm.org) support
View
60 Rakefile
@@ -22,6 +22,8 @@ end
desc "Generate README.md"
task :generate_readme do
rm_r "/tmp/my_cool_extension" if File.exist?("/tmp/my_cool_extension")
+ rm_r "/tmp/my_cool_c_extension" if File.exist?("/tmp/my_cool_c_extension")
+ rm_r "/tmp/my_cool_fdw_extension" if File.exist?("/tmp/my_cool_fdw_extension")
rm_r "/tmp/my_cool_versioned_extension" if File.exist?("/tmp/my_cool_versioned_extension")
readme = File.new("README.md.new", 'w')
readme.puts <<-README
@@ -31,7 +33,7 @@ pgxn utils
What is it?
--------
-It aims to be a set of task to help PostgreSQL extension's developers to focus more on the problem that they wants to solve than in all structure and files and control files need to PGXS to build the extension.
+It is a set of task that help developers to create PostgreSQL's extensions, putting the extension's files in the recomended places and supplying tasks to help bundle and release your extension to PGXN.
How to install it?
------------------
@@ -57,14 +59,46 @@ It is all about tasks. Let's see them:
$ pgxn-utils skeleton my_cool_extension
#{format_cmd_output("skeleton my_cool_extension -p /tmp")}
-You can start creating an extension with or without version control. By default `pgxn-utils`
+Thats it! Just start coding! ":)
+
+## Git support
+
+You can start a new extension with or without version control. By default `pgxn-utils`
supports [git](http://git-scm.org) but it will not create a repository unless you use `--git`
option in the skeleton task.
$ pgxn-utils skeleton my_cool_versioned_extension --git
#{format_cmd_output("skeleton my_cool_versioned_extension --git -p /tmp")}
-Thats it! Just start coding! ":)
+
+When you create a new extension with git support in addition to create skeleton,
+`pgxn-utils` will initialize a git repository and create the initial commit.
+
+Once you have your extension in a git repository your `bundle` will use only the
+commited files to create the archive, but if your repository is dirty then `pgxn-utils`
+will hint you to commit or stash your changes, before bundle.
+
+You must be careful with new files not added to repository, because they will NOT
+be archived.
+
+## Default templates
+
+`pgxn-utils` has three templates: `sql`, `c` and `fdw`. If you call `skeleton` without
+specifying a template the `sql` is the default. But if your extension will supply some C
+modules or you will create a FDW, you can create the extension calling `skeleton` with a
+`--template` option.
+
+ $ pgxn-utils skeleton my_cool_c_extension --template=c
+#{format_cmd_output("skeleton my_cool_c_extension --template=c -p /tmp")}
+
+
+ $ pgxn-utils skeleton my_cool_fdw_extension --template=fdw
+#{format_cmd_output("skeleton my_cool_fdw_extension --template=fdw -p /tmp")}
+
+The templates contains examples codes and some links to PostgreSQL documentation
+that will try to help you to start coding. SQL and C templates contains some tests
+examples, and the example code will compiles and pass `make installcheck`, but they
+are examples and you must write your own tests and code.
# Changing something
@@ -73,7 +107,7 @@ Well suppose you want to change the default maintainer's name and the license, j
$ pgxn-utils change my_cool_extension --maintainer "Dickson Guedes" --license bsd
#{format_cmd_output("change my_cool_extension -p /tmp --maintainer 'Dickson Guedes' --license bsd")}
-It will wait you decide what to do.
+It will wait until you decide what to do.
For all switches that you can use with *change*, type:
@@ -83,8 +117,11 @@ For all switches that you can use with *change*, type:
# Bundling and Releasing!
Well, since you finished your work you can bundle it to send to [PGXN](http://pgxn.org).
+Note that if you have your extension in a git repository `bundle` will use only the
+commited files to create the archive, but if your repository is dirty then `pgxn-utils`
+will hint you to commit or stash your changes, before bundle.
-Bundle it:
+Let's bundle it:
$ pgxn-utils bundle my_cool_extension
create /home/guedes/extensions/my_cool_extension-0.0.1.zip
@@ -100,19 +137,6 @@ and release it:
You can export `PGXN_USER` and `PGXN_PASSWORD` environment variables to avoid
type username and password everytime.
-# Git support
-
-You can start a new extension with git support calling `skeleton` task with
-`--git` flag, then in addition to create skeleton, `pgxn-utils` will initialize
-a git repository and do a initial commit.
-
-Once you have your extension in a git repository your `bundle` will use only the
-commited files to create the archive, but if your repository is dirty then `pgxn-utils`
-will hint you to commit or stash your changes, before bundle.
-
-You must be careful with new files not added to repository, because they will NOT
-be archived.
-
# Working in progress
* improve [git](http://git-scm.org) support
Please sign in to comment.
Something went wrong with that request. Please try again.