Permalink
Browse files

Change README to use AsciiDoc

  • Loading branch information...
1 parent 0fb7d7f commit a8884c1924193e856c4f0de42c952d3e105905bc @sattvik committed Dec 24, 2011
Showing with 369 additions and 388 deletions.
  1. +369 −0 README.asciidoc
  2. +0 −388 README.rst
View
@@ -0,0 +1,369 @@
+Neko: The Clojure/Android Toolkit
+=================================
+Daniel Solano_Gómez
+
+Neko is a toolkit designed to make Android development using Clojure easier and
+more fun. It accomplishes this by making adding Clojure support to your
+Android project easy and providing functional wrappers and alternatives to
+Android’s Java API.
+
+Features
+--------
+
+WARNING: Note that the libraries are under heavy development. APIs are subject
+to change. In particular, `neko.threading` will be changed.
+
+The toolkit comes as two components:
+
+. Simplified build support for Clojure using Android’s Ant-based build system,
+ and
+
+. The following Clojure libraries:
+
+ * `neko.compilation` helps set up dynamic compilation.
+
+ * `neko.context` helps retrieve resources from the application’s context.
+
+ * `neko.listeners` contains namespaces that take the tedium to adding
+ callback code to various widgets.
+
+ * `neko.log` interns functions that make logging from your code clean and
+ simple.
+
+ * `neko.threading` will contain utilities to manage asynchronous tasks and
+ working with UI threads.
+
+
+=== Requirements ===
+
+Using Neko requires the following:
+
+Clojure::
+ Other versions have not been tested. If you would like to use dynamic
+ compilation or support API level 7 (2.1/Eclair), you will need to use the
+ Clojure from branch `android-1.2.x` available from
+ https://github.com/sattvik/clojure/tree/android-1.2.x[this repository on
+ GitHub].
+
+
+Android SDK Tools::
+ Neko has been developed with the latest revision of the Android SDK tools,
+ and is compatible with r14 and up of the Android SDK.
+
+WARNING: Revision 14 of the Android SDK introduced some major changes in the
+Ant build system. Neko has been updated to use the new build system. You will
+probably need to change your project if you have been using an older version of
+Neko/SDK. For more detailed information, check the
+http://tools.android.com/recent/buildchangesinrevision14[Android Tools Project
+Site].
+
+
+Android Platform SDK 7 (2.1/Eclair) or newer::
+ In order to maintain backwards-compatibility, Neko does not support any APIs
+ for newer versions of the platform.
+
+
+Use
+---
+
+The following instructions should help you to add Clojure support to your
+project’s build and allow you to use the libraries within your application.
+
+=== Build support ===
+
+To use Neko’s build support for Clojure, you will need to make two
+modifications to your project’s `build.xml` file.
+
+. You must add a line to similar to the following *before the line with
+ `<import file="${sdk.dir}/tools/ant/build.xml" />`*.
++
+----
+<import file="/path/to/neko/build-support/clojure.xml"/>
+----
++
+The important thing is that the value of the `file` attribute should resolve
+to the `clojure.xml` in the `build-support` directory of this
+repository. It may be either a relative or absolute path.
+
+. You must find the line that reads `<!-- version-tag: 1 -->` and change the
+ `1` to `custom`. If you do not do this, Android may overwrite your changes.
+
+For most projects, that is all you have to do. So long as your Clojure source
+files are in `src/clojure` and you have placed a Clojure JAR file in
+`libs`, Ant will now automatically find and compile all of your Clojure code.
+
+
+==== Reflection warnings ====
+
+To enable reflection warnings during compilation, simply set the
+`clojure.warn.reflection` property to `true`.
+
+
+==== `clojure.properties` ====
+
+You can place a `clojure.properties` file in the same directory as the
+`clojure.xml` file. This file will be sourced and used in any project in which
+you have enabled Clojure support.
+
+==== Test and library projects ====
+
+If your project is a test or library project, you should not place a copy of
+the Clojure library in the `libs` directory. If you do this, when building an
+application that uses your library or when building your test project, the `dx`
+tool will fail due to multiple inclusions of the same Clojure classes.
+
+In these circumstances, you should either set a `clojure.jar` property in your
+project’s `build.properties` file or in the `clojure.properties` file as
+described in the previous section.
+
+Also, if you are developing an Android library project, you should add the
+following line to your `build.properties` file:
+
+----
+source.dir=src/java
+----
+
+This will ensure that your Clojure sources are not inadvertently included in
+any applications that use your library.
+
+=== Libraries ===
+
+Neko is packaged as an Android library project. This makes it easy to add the
+libraries to your application if you are using Android’s build system.
+Essentially, all you have to do is add a line to your project’s
+`build.properties` similar to the following:
+
+----
+android.library.reference.1=/path/to/neko
+----
+
+Where the path is either absolute or relative and resolves to the base
+directory for Neko. To learn more about Android library projects, you can read
+the SDK documentation for referencing a library project in
+http://developer.android.com/guide/developing/projects/projects-eclipse.html#ReferencingLibraryProject[Eclipse]
+or
+http://developer.android.com/guide/developing/projects/projects-cmdline.html#ReferencingLibraryProject[from
+the command line].
+
+
+
+Legal information
+-----------------
+
+Copyright © 2011 Sattvik Software & Technology Resources, Ltd. Co. +
+All rights reserved.
+
+=== Eclipse Public License - v 1.0 ===
+
+THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC
+LICENSE (“AGREEMENT”). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE
+PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT.
+
+==== 1. DEFINITIONS ====
+
+“Contribution” means:
+
+a. in the case of the initial Contributor, the initial code and documentation
+ distributed under this Agreement, and
+
+b. in the case of each subsequent Contributor:
+
+ i) changes to the Program, and
+
+ ii) additions to the Program;
++
+where such changes and/or additions to the Program originate from and are
+distributed by that particular Contributor. A Contribution ‘originates’ from a
+Contributor if it was added to the Program by such Contributor itself or anyone
+acting on such Contributor’s behalf. Contributions do not include additions to
+the Program which: (i) are separate modules of software distributed in
+conjunction with the Program under their own license agreement, and (ii) are
+not derivative works of the Program.
+
+“Contributor” means any person or entity that distributes the Program.
+
+“Licensed Patents” mean patent claims licensable by a Contributor which are
+necessarily infringed by the use or sale of its Contribution alone or when
+combined with the Program.
+
+“Program” means the Contributions distributed in accordance with this
+Agreement.
+
+“Recipient” means anyone who receives the Program under this Agreement,
+including all Contributors.
+
+==== 2. GRANT OF RIGHTS ====
+
+a. Subject to the terms of this Agreement, each Contributor hereby grants
+ Recipient a non-exclusive, worldwide, royalty-free copyright license to
+ reproduce, prepare derivative works of, publicly display, publicly perform,
+ distribute and sublicense the Contribution of such Contributor, if any, and
+ such derivative works, in source code and object code form.p>
+
+b. Subject to the terms of this Agreement, each Contributor hereby grants
+ Recipient a non-exclusive, worldwide, royalty-free patent license under
+ Licensed Patents to make, use, sell, offer to sell, import and otherwise
+ transfer the Contribution of such Contributor, if any, in source code and
+ object code form. This patent license shall apply to the combination of the
+ Contribution and the Program if, at the time the Contribution is added by
+ the Contributor, such addition of the Contribution causes such combination
+ to be covered by the Licensed Patents. The patent license shall not apply to
+ any other combinations which include the Contribution. No hardware per se is
+ licensed hereunder.
+
+c. Recipient understands that although each Contributor grants the licenses to
+ its Contributions set forth herein, no assurances are provided by any
+ Contributor that the Program does not infringe the patent or other
+ intellectual property rights of any other entity. Each Contributor disclaims
+ any liability to Recipient for claims brought by any other entity based on
+ infringement of intellectual property rights or otherwise. As a condition to
+ exercising the rights and licenses granted hereunder, each Recipient hereby
+ assumes sole responsibility to secure any other intellectual property rights
+ needed, if any. For example, if a third party patent license is required to
+ allow Recipient to distribute the Program, it is Recipient’s responsibility
+ to acquire that license before distributing the Program.
+
+d. Each Contributor represents that to its knowledge it has sufficient
+ copyright rights in its Contribution, if any, to grant the copyright license
+ set forth in this Agreement.
+
+==== 3. REQUIREMENTS ====
+
+A Contributor may choose to distribute the Program in object code form under
+its own license agreement, provided that:
+
+a. it complies with the terms and conditions of this Agreement; and
+
+b. its license agreement:
+
+ i) effectively disclaims on behalf of all Contributors all warranties and
+ conditions, express and implied, including warranties or conditions of title
+ and non-infringement, and implied warranties or conditions of
+ merchantability and fitness for a particular purpose;
+
+ ii) effectively excludes on behalf of all Contributors all liability for
+ damages, including direct, indirect, special, incidental and consequential
+ damages, such as lost profits;
+
+ iii) states that any provisions which differ from this Agreement are offered
+ by that Contributor alone and not by any other party; and
+
+ iv) states that source code for the Program is available from such
+ Contributor, and informs licensees how to obtain it in a reasonable manner
+ on or through a medium customarily used for software exchange.
+
+When the Program is made available in source code form:
+
+a. it must be made available under this Agreement; and
+
+b. a copy of this Agreement must be included with each copy of the Program.
+
+Contributors may not remove or alter any copyright notices contained within the
+Program.
+
+Each Contributor must identify itself as the originator of its Contribution, if
+any, in a manner that reasonably allows subsequent Recipients to identify the
+originator of the Contribution.
+
+==== 4. COMMERCIAL DISTRIBUTION ====
+
+Commercial distributors of software may accept certain responsibilities with
+respect to end users, business partners and the like. While this license is
+intended to facilitate the commercial use of the Program, the Contributor who
+includes the Program in a commercial product offering should do so in a manner
+which does not create potential liability for other Contributors. Therefore, if
+a Contributor includes the Program in a commercial product offering, such
+Contributor (“Commercial Contributor”) hereby agrees to defend and indemnify
+every other Contributor (“Indemnified Contributor”) against any losses, damages
+and costs (collectively “Losses”) arising from claims, lawsuits and other legal
+actions brought by a third party against the Indemnified Contributor to the
+extent caused by the acts or omissions of such Commercial Contributor in
+connection with its distribution of the Program in a commercial product
+offering. The obligations in this section do not apply to any claims or Losses
+relating to any actual or alleged intellectual property infringement. In order
+to qualify, an Indemnified Contributor must: a) promptly notify the Commercial
+Contributor in writing of such claim, and b) allow the Commercial Contributor
+to control, and cooperate with the Commercial Contributor in, the defense and
+any related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial product
+offering, Product X. That Contributor is then a Commercial Contributor. If that
+Commercial Contributor then makes performance claims, or offers warranties
+related to Product X, those performance claims and warranties are such
+Commercial Contributor’s responsibility alone. Under this section, the
+Commercial Contributor would have to defend claims against the other
+Contributors related to those performance claims and warranties, and if a court
+requires any other Contributor to pay any damages as a result, the Commercial
+Contributor must pay those damages.
+
+==== 5. NO WARRANTY ====
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN
+“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each
+Recipient is solely responsible for determining the appropriateness of using
+and distributing the Program and assumes all risks associated with its exercise
+of rights under this Agreement , including but not limited to the risks and
+costs of program errors, compliance with applicable laws, damage to or loss of
+data, programs or equipment, and unavailability or interruption of operations.
+
+==== 6. DISCLAIMER OF LIABILITY ====
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY
+CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), 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 OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS
+GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+==== 7. GENERAL ====
+
+If any provision of this Agreement is invalid or unenforceable under applicable
+law, it shall not affect the validity or enforceability of the remainder of the
+terms of this Agreement, and without further action by the parties hereto, such
+provision shall be reformed to the minimum extent necessary to make such
+provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Program itself
+(excluding combinations of the Program with other software or hardware)
+infringes such Recipient’s patent(s), then such Recipient’s rights granted
+under Section 2(b) shall terminate as of the date such litigation is filed.
+
+All Recipient’s rights under this Agreement shall terminate if it fails to
+comply with any of the material terms or conditions of this Agreement and does
+not cure such failure in a reasonable period of time after becoming aware of
+such noncompliance. If all Recipient’s rights under this Agreement terminate,
+Recipient agrees to cease use and distribution of the Program as soon as
+reasonably practicable. However, Recipient’s obligations under this Agreement
+and any licenses granted by Recipient relating to the Program shall continue
+and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement, but in
+order to avoid inconsistency the Agreement is copyrighted and may only be
+modified in the following manner. The Agreement Steward reserves the right to
+publish new versions (including revisions) of this Agreement from time to time.
+No one other than the Agreement Steward has the right to modify this Agreement.
+The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation
+may assign the responsibility to serve as the Agreement Steward to a suitable
+separate entity. Each new version of the Agreement will be given a
+distinguishing version number. The Program (including Contributions) may always
+be distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to distribute the Program (including its Contributions)
+under the new version. Except as expressly stated in Sections 2(a) and 2(b)
+above, Recipient receives no rights or licenses to the intellectual property of
+any Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted under
+this Agreement are reserved.
+
+This Agreement is governed by the laws of the State of New York and the
+intellectual property laws of the United States of America. No party to this
+Agreement will bring a legal action under this Agreement more than one year
+after the cause of action arose. Each party waives its rights to a jury trial
+in any resulting litigation.
+
+// vim:set spell ft=asciidoc:
Oops, something went wrong.

0 comments on commit a8884c1

Please sign in to comment.