From c38a4db56a7b780cc1ff6fad864db77754af341e Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 16:07:39 -0800 Subject: [PATCH 1/7] Move README etc. to .md files. * README * CONTRIBUTING * Various INSTALL documents --- CONTRIBUTING => CONTRIBUTING.md | 0 INSTALL => INSTALL.md | 0 README => README.md | 0 compiler/c/{INSTALL => INSTALL.md} | 0 compiler/go/{INSTALL => INSTALL.md} | 0 compiler/perl/{INSTALL => INSTALL.md} | 0 runtime/c/{INSTALL => INSTALL.md} | 0 runtime/go/{INSTALL => INSTALL.md} | 0 runtime/perl/{INSTALL => INSTALL.md} | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename CONTRIBUTING => CONTRIBUTING.md (100%) rename INSTALL => INSTALL.md (100%) rename README => README.md (100%) rename compiler/c/{INSTALL => INSTALL.md} (100%) rename compiler/go/{INSTALL => INSTALL.md} (100%) rename compiler/perl/{INSTALL => INSTALL.md} (100%) rename runtime/c/{INSTALL => INSTALL.md} (100%) rename runtime/go/{INSTALL => INSTALL.md} (100%) rename runtime/perl/{INSTALL => INSTALL.md} (100%) diff --git a/CONTRIBUTING b/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING rename to CONTRIBUTING.md diff --git a/INSTALL b/INSTALL.md similarity index 100% rename from INSTALL rename to INSTALL.md diff --git a/README b/README.md similarity index 100% rename from README rename to README.md diff --git a/compiler/c/INSTALL b/compiler/c/INSTALL.md similarity index 100% rename from compiler/c/INSTALL rename to compiler/c/INSTALL.md diff --git a/compiler/go/INSTALL b/compiler/go/INSTALL.md similarity index 100% rename from compiler/go/INSTALL rename to compiler/go/INSTALL.md diff --git a/compiler/perl/INSTALL b/compiler/perl/INSTALL.md similarity index 100% rename from compiler/perl/INSTALL rename to compiler/perl/INSTALL.md diff --git a/runtime/c/INSTALL b/runtime/c/INSTALL.md similarity index 100% rename from runtime/c/INSTALL rename to runtime/c/INSTALL.md diff --git a/runtime/go/INSTALL b/runtime/go/INSTALL.md similarity index 100% rename from runtime/go/INSTALL rename to runtime/go/INSTALL.md diff --git a/runtime/perl/INSTALL b/runtime/perl/INSTALL.md similarity index 100% rename from runtime/perl/INSTALL rename to runtime/perl/INSTALL.md From ed2aa84b2d30b25ddea8fc8a32ca5f4e6ec903ce Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 16:11:18 -0800 Subject: [PATCH 2/7] Generalize INSTALL for multiple hosts. Don't enumerate available host languages; instead refer to $LANG and "language of choice". --- INSTALL.md | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 75c0a2c4..56b5f609 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,33 +1,24 @@ Build Instructions ================== -The Apache Clownfish "symbiotic" object system pairs with "host" dynamic -language environments and facilitates the development of high performance host -language extensions. Currently, it is available for Perl and plain C -libraries. +Apache Clownfish consists of two parts, the Clownfish compiler "CFC" and the +Clownfish runtime. Apache Clownfish runtime ------------------------ -To build the Clownfish runtime for Perl, chdir to the "runtime/perl" -subdirectory underneath the "clownfish" top level and follow the instructions -in the INSTALL document there. +To build the Clownfish runtime, chdir into the `runtime/$LANG` subdirectory, +where `$LANG` is your programming language of choice, and follow the +instructions in the `INSTALL` document there. -To build the Clownfish runtime for C, chdir to the "runtime/c" subdirectory -underneath the "clownfish" top level and follow the instructions in the -INSTALL document there. - -The Clownfish runtime build requires the Clownfish compiler and will build it -first. +The Clownfish runtime build requires the Clownfish compiler. Some host +language bindings will build it first automaticaly, while others require +manual installation of the compiler as a prerequisite. Apache Clownfish compiler ------------------------- -To only build the Clownfish compiler with Perl bindings, chdir to the -"compiler/perl" subdirectory underneath the "clownfish" top level and follow -the instructions in the INSTALL document there. - -To only build the Clownfish compiler "cfc" executable, chdir to the -"compiler/c" subdirectory underneath the "clownfish" top level and follow the -instructions in the INSTALL document there. +To build only the Clownfish compiler, chdir into the `compiler/$LANG` +subdirectory, where `$LANG` is your programming language of choice, and follow +the instructions in the `INSTALL` document there. From 292dad11a3063b2d3955ab99fdc1b55d3784c846 Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 16:13:10 -0800 Subject: [PATCH 3/7] Remove dated Module::Build explanation. Module::Build is no longer bundled with Perl. --- compiler/perl/INSTALL.md | 4 ---- runtime/perl/INSTALL.md | 4 ---- 2 files changed, 8 deletions(-) diff --git a/compiler/perl/INSTALL.md b/compiler/perl/INSTALL.md index 77823b01..fd08127f 100644 --- a/compiler/perl/INSTALL.md +++ b/compiler/perl/INSTALL.md @@ -9,7 +9,3 @@ following commands: perl Build test perl Build install -Module::Build is required. Since Perl 5.10.0, Module::Build has been bundled -with the Perl core, but on older systems it may be necessary to install it -from CPAN first. - diff --git a/runtime/perl/INSTALL.md b/runtime/perl/INSTALL.md index 60185e0f..824af321 100644 --- a/runtime/perl/INSTALL.md +++ b/runtime/perl/INSTALL.md @@ -9,7 +9,3 @@ commands: perl Build test perl Build install -Module::Build is required. Since Perl 5.10.0, Module::Build has been bundled -with the Perl core, but on older systems it may be necessary to install it -from CPAN first. - From d5b2474617c80081a3facf3a3a55a353b604bc4f Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 16:27:40 -0800 Subject: [PATCH 4/7] Update Go INSTALL instructions. Make the instructions compatible with installing from the official release tarball, in addition to compatible with installing from a Git checkout. --- compiler/go/INSTALL.md | 15 ++++++++++----- runtime/go/INSTALL.md | 12 ++++-------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/compiler/go/INSTALL.md b/compiler/go/INSTALL.md index 3d44031e..0276482d 100644 --- a/compiler/go/INSTALL.md +++ b/compiler/go/INSTALL.md @@ -1,18 +1,23 @@ Apache Clownfish symbiotic object system -- CFC compiler Go bindings -------------------------------------------------------------------- -These are temporary installation instructions for developers working on the -Apache Clownfish Go (golang) bindings. +To install from an official release of Clownfish: -Make sure you have your GOPATH set, then clone the Clownfish git repository. + mkdir -p $GOPATH/src/git-wip-us.apache.org/repos/asf/lucy.git + tar -C $GOPATH/src/git-wip-us.apache.org/repos/asf/lucy.git \ + -zxf apache-clownfish-0.5.0.tgz + +Developers actively working on Clownfish may instead clone from the Clownfish +Git repository: mkdir -p $GOPATH/src/git-wip-us.apache.org/repos/asf cd $GOPATH/src/git-wip-us.apache.org/repos/asf git clone https://git-wip-us.apache.org/repos/asf/lucy-clownfish.git lucy-clownfish.git - cd lucy-clownfish.git/compiler/go -From the `compiler/go` directory within the checkout, run `build.go`: +Once the source code is in place, from the `compiler/go` directory within the +checkout, run `build.go`: + cd $GOPATH/src/git-wip-us.apache.org/repos/asf/lucy-clownfish.git/compiler/go go run build.go go run build.go test go run build.go install diff --git a/runtime/go/INSTALL.md b/runtime/go/INSTALL.md index c5db4887..7a29c59c 100644 --- a/runtime/go/INSTALL.md +++ b/runtime/go/INSTALL.md @@ -1,17 +1,13 @@ Apache Clownfish symbiotic object system -- runtime Go bindings --------------------------------------------------------------- -These are temporary installation instructions for developers working on the -Apache Clownfish Go bindings. - As a prerequisite, install the Go bindings for the Clownfish compiler (CFC). -This will entail cloning the Git repository which is shared by the runtime. - - # After installing CFC, switch to the runtime/go directory. - cd $GOPATH/src/git-wip-us.apache.org/repos/asf/lucy-clownfish.git/runtime/go +This will entail installing the shared source tree for Clownfish, which +includes the source code for both the compiler and the runtime. -From the `runtime/go` directory within the checkout, run `build.go`: +After installing CFC, switch to the `runtime/go` directory and run `build.go`: + cd $GOPATH/src/git-wip-us.apache.org/repos/asf/lucy-clownfish.git/runtime/go go run build.go go run build.go test go run build.go install From 63212700998e8fffdefdabd28d903295491c926f Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 16:44:55 -0800 Subject: [PATCH 5/7] Rework top-level README and Clownfish.md. Now that we have functional C and Go bindings, cast Clownfish as being developed for multiple languages and de-emphasize Perl. Change "dynamic languages" to "programming languages", as Go is not dynamic. Add a "Help wanted" section and state explicitly that the target audience for this release is developers. --- README.md | 30 +++++++++++++++++++++++++----- runtime/core/Clownfish.md | 28 +++++++++++++++++++++++----- 2 files changed, 48 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8bc4d46c..1bab629b 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,34 @@ Apache Clownfish ================ -OVERVIEW +The Apache Clownfish "symbiotic" object system pairs with "host" programming +language environments and facilitates the development of high performance +language extensions. -The Apache Clownfish "symbiotic" object system pairs with "host" dynamic -language environments and facilitates the development of high performance host -language extensions. Currently, it is a subproject of Apache Lucy. +Host language support +--------------------- -INSTALLATION +Bindings for the following hosts are under development: + +* C (feature-complete) +* Go (experimental) +* Perl 5 (feature-complete) +* Python 3 / CPython (nascent) +* Ruby / MRI (nascent) + +Installation +------------ To build and install Apache Clownfish, follow the instructions in the accompanying "INSTALL" document. +Help wanted +----------- + +The target audience for the current release of Clownfish is developers. +Clownfish is developed by the Apache Lucy community, where it is used to +provide host language bindings for the Lucy search engine library; we expect +that as Clownfish matures it will eventually spin off as an independent +project. If you would like to contribute to Clownfish, please join the [Lucy +developers mailing list](http://lucy.apache.org/mailing_lists). + diff --git a/runtime/core/Clownfish.md b/runtime/core/Clownfish.md index 058eb12d..8caa761b 100644 --- a/runtime/core/Clownfish.md +++ b/runtime/core/Clownfish.md @@ -1,13 +1,12 @@ # Apache Clownfish symbiotic object system -Apache Clownfish is a "symbiotic" object system for C which is designed to -pair with a "host" dynamic language environment, facilitating the development -of high performance host language extensions. +The Apache Clownfish "symbiotic" object system pairs with "host" programming +language environments and facilitates the development of high performance +language extensions. ## Features -* Designed to support multiple host languages. Currently, only Perl is - supported. +* Support for multiple host languages. * Support for stand-alone C libraries and executables. * Subclassing and method overriding from the host language. * Support for host language idioms like named parameters or default argument @@ -52,6 +51,25 @@ The Clownfish runtime provides: * The [](cfish.Class) metaclass. * Some helper classes. +## Host language support + +Bindings for the following hosts are under development: + +* C (feature-complete) +* Go (experimental) +* Perl 5 (feature-complete) +* Python 3 / CPython (nascent) +* Ruby / MRI (nascent) + +## Help wanted + +The target audience for the current release of Clownfish is developers. +Clownfish is developed by the Apache Lucy community, where it is used to +provide host language bindings for the Lucy search engine library; we expect +that as Clownfish matures it will eventually spin off as an independent +project. If you would like to contribute to Clownfish, please join the [Lucy +developers mailing list](http://lucy.apache.org/mailing_lists). + ## Documentation * [Working with Clownfish classes](ClassIntro) From 608979f9376596d8ce76bd91bb099cfca945b20a Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 17:09:57 -0800 Subject: [PATCH 6/7] Reformat CONTRIBUTING as Markdown. --- CONTRIBUTING.md | 116 +++++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 60 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10c92d95..52195ad5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,89 +1,85 @@ -================================ Contributing to Apache Clownfish ================================ -MAKE A PLAN: - - Clownfish is developed by the Apache Lucy community. +Make a plan +----------- - http://lucy.apache.org/ +Clownfish is developed by the [Apache Lucy](http://lucy.apache.org) community. - If you propose to make non-trivial changes to Clownfish, especially changes - to the public API, send a note to the Lucy developer's list describing your - plans: +If you propose to make non-trivial changes to Clownfish, especially changes +to the public API, send a note to the [Lucy developer's +list](http://lucy.apache.org/mailing_lists) describing your plans. - http://lucy.apache.org/mailing_lists.html - -GET THE CODE: +Get the code +------------ - Clownfish's codebase is available via Git from git-wip-us.apache.org. Start - by creating a clone of the repository: +Clownfish's codebase is available via Git from git-wip-us.apache.org. Start +by creating a clone of the repository: git clone https://git-wip-us.apache.org/repos/asf/lucy-clownfish.git - There is also a mirror on Github. +There is also a [mirror on Github](https://github.com/apache/lucy-clownfish). - https://github.com/apache/lucy-clownfish +Follow the instructions in INSTALL to set up your local workspace. - Follow the instructions in INSTALL to set up your local workspace. +Make changes +------------ -MAKE CHANGES: +Edit the source code as you see fit, then build and run tests. - Edit the source code as you see fit, then build and run tests. +Clownfish supports continuous integration services Travis and Appveyor +to run tests under multiple host languages, host language versions, and +platforms. If you fork the Github repository, you can make these services +automatically test the changes you made in your fork. - Clownfish supports continuous integration services Travis and Appveyor - to run tests under multiple host languages, host language versions, and - platforms. If you fork the Github repository, you can make these services - automatically test the changes you made in your fork. +Please bear the following in mind: - Please bear the following in mind: +* All code will eventually need to be portable to multiple operating + systems and compilers. (This is a complex requirement and it should not + block your contribution.) +* All public APIs must be documented. +* Code should be formatted according to the style guidelines at + . +* All unit tests must pass. +* New code needs to be accompanied by new unit tests. +* Simplicity, both in terms of API and implementation, is highly valued + within the Lucy development community; the simpler the contribution, the + more quickly it can be reviewed and integrated. - * All code will eventually need to be portable to multiple operating - systems and compilers. (This is a complex requirement and it should not - block your contribution.) - * All public APIs must be documented. - * Code should be formatted according to the style guidelines at - . - * All unit tests must pass. - * New code needs to be accompanied by new unit tests. - * Simplicity, both in terms of API and implementation, is highly valued - within the Lucy development community; the simpler the contribution, the - more quickly it can be reviewed and integrated. +Open an issue +------------- -OPEN AN ISSUE: +The [Clownfish issue-tracker](https://issues.apache.org/jira/browse/CLOWNFISH) +runs Atlassian JIRA and we generally use the term "issue" rather than "bug" +because not every contribution fixes a "bug": - Clownfish uses Lucy's issue-tracker/bug-tracker installation, which runs - Atlassian JIRA. We generally use the term "issue" rather than "bug" because - not every contribution fixes a "bug". - - https://issues.apache.org/jira/browse/CLOWNFISH - - 1. Create a JIRA account for yourself and sign in. - 2. Once you have signed in, the "create new issue" link will appear. Either - use it to open a new issue or navigate to an existing one as appropriate. - 3. To attach files to an issue, use the menu command - 'More Actions > Attach Files'. +1. Create a JIRA account for yourself and sign in. +2. Once you have signed in, the "create new issue" link will appear. Either + use it to open a new issue or navigate to an existing one as appropriate. +3. To attach files to an issue, use the menu command + 'More Actions > Attach Files'. - Attaching a file to an issue causes an email notification to be sent to the - lucy-issues list signalling that a patch has arrived. Please be patient but - persistent while engaging with the Lucy committers who review and apply such - patches. +Attaching a file to an issue causes an email notification to be sent to the +lucy-issues list signalling that a patch has arrived. Please be patient but +persistent while engaging with the Lucy committers who review and apply such +patches. -CONTRIBUTE A PATCH: +Contribute a patch +------------------ - The easiest way to create a patch with Git is to capture the output of - `git diff`: +The easiest way to create a patch with Git is to capture the output of +`git diff`: git diff > my_changes.patch - The resulting patch file can then be attached to a JIRA issue. - -GITHUB PULL REQUESTS +The resulting patch file can then be attached to a JIRA issue. - Github users may submit pull requests against our mirror: +Github pull requests +-------------------- - https://github.com/apache/lucy-clownfish +Github users may submit pull requests against our +[mirror](https://github.com/apache/lucy-clownfish). - An email notifying the Lucy developers list of your pull request will be - triggered automatically. +An email notifying the Lucy developers list of your pull request will be +triggered automatically. From da25c965550687e2c85f3093d3b6d0867dfd47ec Mon Sep 17 00:00:00 2001 From: Marvin Humphrey Date: Wed, 30 Dec 2015 17:21:08 -0800 Subject: [PATCH 7/7] Rework CONTRIBUTING.md to prefer Github. --- CONTRIBUTING.md | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52195ad5..5749766e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,16 @@ Please bear the following in mind: within the Lucy development community; the simpler the contribution, the more quickly it can be reviewed and integrated. +Github pull requests +-------------------- + +Github users may submit pull requests against our +[mirror](https://github.com/apache/lucy-clownfish). An email notifying the +Lucy developers list of your pull request will be triggered automatically. + +Ideally, open a JIRA issue and reference it by its `CLOWNFISH-NNN` identifier +in your pull request -- but this is not required. + Open an issue ------------- @@ -56,30 +66,22 @@ because not every contribution fixes a "bug": 1. Create a JIRA account for yourself and sign in. 2. Once you have signed in, the "create new issue" link will appear. Either use it to open a new issue or navigate to an existing one as appropriate. -3. To attach files to an issue, use the menu command - 'More Actions > Attach Files'. - -Attaching a file to an issue causes an email notification to be sent to the -lucy-issues list signalling that a patch has arrived. Please be patient but -persistent while engaging with the Lucy committers who review and apply such -patches. -Contribute a patch ------------------- +Attach a patch to an issue +-------------------------- -The easiest way to create a patch with Git is to capture the output of -`git diff`: +If you are not a Github user, you may propose changes by submitting patches +via JIRA. The easiest way to create a patch with Git is to capture the output +of `git diff`: git diff > my_changes.patch -The resulting patch file can then be attached to a JIRA issue. - -Github pull requests --------------------- - -Github users may submit pull requests against our -[mirror](https://github.com/apache/lucy-clownfish). +The resulting patch file can then be attached to a JIRA issue. Make sure that +you are logged in as a JIRA user, then select the menu command 'More Actions > +Attach Files'. -An email notifying the Lucy developers list of your pull request will be -triggered automatically. +Attaching a file to an issue causes an email notification to be sent to the +lucy-issues list signalling that a patch has arrived. Please be patient but +persistent while engaging with the Lucy committers who review and apply such +patches.