[Jython-checkins] jython: Provide README.(md|txt) with distinct content (completes #2764)
jeff.allen
jython-checkins at python.org
Sat Jul 20 17:16:29 EDT 2019
https://hg.python.org/jython/rev/5deb7d7984e8
changeset: 8255:5deb7d7984e8
user: Jeff Allen <ja.py at farowl.co.uk>
date: Sat Jul 20 19:51:23 2019 +0100
summary:
Provide README.(md|txt) with distinct content (completes #2764)
This reflects the idea that README.md describes the project for GitHub
visitors (build instructions, etc.), and README.txt is to be seen
during/after installation. Also, note our use of Gradle as a feature.
files:
NEWS | 4 +
README.md | 88 +++++++++++++++++++++++++++++++++++++++---
2 files changed, 84 insertions(+), 8 deletions(-)
diff --git a/NEWS b/NEWS
--- a/NEWS
+++ b/NEWS
@@ -5,6 +5,7 @@
Development tip
Bugs fixed
+ - [ 2764 ] Readme is not displayed when using the GUI installer
- [ 2345 ] Installing pip fails if JYTHON_HOME points to old installation
- [ 2774 ] test_ssl failures from weak certificate
- [ 2768 ] Allow bytearray + and += to accept buffer protocol objects
@@ -69,6 +70,9 @@
- We no longer recommend overriding toString in PyObject sub-classes as a way of defining
string forms. Override __repr__, and if necessary __str__, as is usual in Python. We
recommend toString should return the same as __str__ (or __unicode__).
+ - Experimentally, we use Gradle to build a JAR and POM that may be cited as a dependency by
+ other projects. The Jython project would like to know if this is being done suitably
+ for downstream use.
Jython 2.7.2a1
Bugs fixed
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1,16 +1,88 @@
# Jython: Python for the Java Platform
-[](https://search.maven.org/artifact/org.python/jython-standalone/) [](https://www.javadoc.io/doc/org.python/jython-standalone)
+[](https://search.maven.org/artifact/org.python/jython-standalone/)
+[](https://www.javadoc.io/doc/org.python/jython-standalone)
+
+This is the development repository of Jython,
+the implementation of Python 2.7 in Java.
+Along with good (not perfect!) language
+and runtime compatibility with CPython 2.7,
+Jython 2.7 provides substantial support of the Python ecosystem.
+This includes built-in support of *pip/setuptools*
+(you can use `bin/pip` if the targets do not include `C` extensions)
+and a native launcher for Windows (`bin/jython.exe`)
+that works essentially as the `python` command.
+
+Jim Baker presented a talk at PyCon 2015 about Jython 2.7,
+including demos of new features: https://www.youtube.com/watch?v=hLm3garVQFo
-This is the development repository of Jython. Along with language and runtime compatibility with CPython 2.7, Jython 2.7 provides substantial support of the Python ecosystem. This includes built-in support of *pip/setuptools* (you can use with `bin/pip`) and a native launcher for Windows (`bin/jython.exe`), with the implication that you can finally install Jython scripts on Windows.
+See [ACKNOWLEDGMENTS](ACKNOWLEDGMENTS) for details about Jython's copyright,
+license, contributors, and mailing lists.
+Consult [NEWS](NEWS) for detailed release notes, including bugs fixed,
+backwards breaking changes, and new features.
+We sincerely thank all who contribute to Jython, by bug reports, patches,
+pull requests, documentation changes and e-mail discussions.
-Jim Baker presented a talk at PyCon 2015 about Jython 2.7, including demos of new features: https://www.youtube.com/watch?v=hLm3garVQFo
+## How to build Jython
+
+The project uses Mercurial for version-control,
+and the master repository is at https://hg.python.org/jython/,
+while the repository on GitHub is just a mirror of that.
+You may clone either repository to create a buildable copy of the latest state
+of the Jython source.
+
+### Build using `ant` for development
-Please try this release out and report any bugs at http://bugs.jython.org
+Jython is normally built using `ant`.
+It is necessary to have Ant and at least a Java 7 SDK on the path.
+To build Jython development use, we generally use the command:
+```
+ant
+```
+This leaves an executable in `dist/bin`
+that you may run from the check-out root with:
+```
+dist/bin/jython
+```
+Other `ant` targets exist, notably `clean`, and `jar`.
-You can test your installation of Jython (not the standalone jar) by running the regression tests, with the command:
+You can test your build of Jython (by running the regression tests),
+with the command:
+```
+dist/bin/jython -m test.regrtest -e -m regrtest_memo.txt
+```
+
+### Build an installer using `ant`
+
+If you want to install a snapshot build of Jython, use the command:
+```
+ant installer
```
-jython -m test.regrtest -e -m regrtest_memo.txt
+This will leave you with a snapshot installer JAR in `dist`,
+that you can run with:
+```
+java -jar jython-installer.jar
+```
+for the graphical installer, or:
+```
+java -jar jython-installer.jar --console
```
-For Windows, there is a simple script to do this: `jython_regrtest.bat`. In either case, the memo file `regrtest_memo.txt` will be useful in the bug report if you see test failures. The regression tests can take about half an hour.
+For the console version. (A `--help` option gives you the full story.)
+
+### Build a JAR using Gradle
-See [ACKNOWLEDGMENTS](ACKNOWLEDGMENTS) for details about Jython's copyright, license, contributors, and mailing lists; and [NEWS](NEWS) for detailed release notes, including bugs fixed, backwards breaking changes, and new features. We sincerely thank all who contribute to Jython, including - but not limited to - bug reports, patches, pull requests, documentation changes, support emails, and fantastic conversation on Freenode at #jython. Join us there for your questions and answers!
+Experimentally, we have a Gradle build that results in a family of JARs,
+and a POM.
+This is intended to provide the Jython core in a form that Gradle and Maven
+users can consume as a dependency.
+Invoke this with:
+```
+PS> .\gradlew publish
+```
+and a JAR and POM are delivered to ` .build2\repo`
+
+Whereas the JARs delivered by the installer are somewhat "fat",
+embedding certain dependencies in shaded (renamed) form,
+the JARs from the Gradle build are "spare"
+and cite their dependencies externally through a POM.
+The project would like to know if this is being done suitably
+for downstream use.
--
Repository URL: https://hg.python.org/jython
More information about the Jython-checkins
mailing list