You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pekko.apache.org by fa...@apache.org on 2023/06/19 10:04:19 UTC
[incubator-pekko-http] branch main updated: add build docs (#180)
This is an automated email from the ASF dual-hosted git repository.
fanningpj pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-pekko-http.git
The following commit(s) were added to refs/heads/main by this push:
new 8f6c63b1a add build docs (#180)
8f6c63b1a is described below
commit 8f6c63b1a69dc5d5eac90e155f137b9e436ec13e
Author: PJ Fanning <pj...@users.noreply.github.com>
AuthorDate: Mon Jun 19 11:04:14 2023 +0100
add build docs (#180)
* add build docs
* Update README.md
* only java 8 needed
* point out that it is JDK 8 that is needed
* mention JDK 11
* Update README.md
---
README.md | 51 ++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 40 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index fa6ec8da6..f60b8dbcf 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-Apache Pekko HTTP
-=================
+# Apache Pekko HTTP
<!--
[](https://index.scala-lang.org/pekko/pekko-http/pekko-http-core)
@@ -22,21 +21,52 @@ might require you to write more application code.
Learn more at [pekko.apache.org](https://pekko.apache.org/docs/pekko-http/current/).
-Documentation
--------------
+## Documentation
The documentation is available at
[pekko.apache.org](https://pekko.apache.org/docs/pekko-http/current/), for
[Scala](https://pekko.apache.org/docs/pekko-http/current/scala/http/) and
[Java](https://pekko.apache.org/docs/pekko-http/current/java/http/).
-
-Community
----------
+## Building from Source
+
+### Prerequisites
+- Make sure you have installed a Java Development Kit (JDK) version 8 or later.
+- You will need Java Development Kit (JDK) version 11 or later when building the docs.
+- Make sure you have [sbt](https://www.scala-sbt.org/) installed.
+- [Graphviz](https://graphviz.gitlab.io/download/) is needed for the scaladoc generation build task, which is part of the release.
+
+### Running the Build
+- Open a command window and change directory to your preferred base directory
+- Use git to clone the [repo](https://github.com/apache/incubator-pekko-http) or download a source release from https://pekko.apache.org (and unzip or untar it, as appropriate)
+- Change directory to the directory where you installed the source (you should have a file called `build.sbt` in this directory)
+- `sbt compile` compiles the main source for project default version of Scala (2.13)
+ - `sbt +compile` will compile for all supported versions of Scala
+- `sbt test` will compile the code and run the unit tests
+- `sbt package` will build the jars
+ - the jars will built into target dirs of the various modules
+ - for the the 'http-core' module, the jar will be built to `http-core/target/scala-2.13/`
+- `sbt publishLocal` will push the jars to your local Apache Ivy repository
+- `sbt publishM2` will push the jars to your local Apache Maven repository
+- `sbt docs/paradox` will build the docs (the ones describing the module features)
+ - requires JDK 11 or above
+ - `sbt docs/paradoxBrowse` does the same but will open the docs in your browser when complete
+ - the `index.html` file will appear in `target/paradox/site/main/`
+- `sbt unidoc` will build the Javadocs for all the modules and load them to one place (may require Graphviz, see Prerequisites above)
+ - the `index.html` file will appear in `target/scala-2.13/unidoc/`
+- `sbt sourceDistGenerate` will generate source release to `target/dist/`
+- The version number that appears in filenames and docs is derived, by default. The derived version contains the most git commit id or the date/time (if the directory is not under git control).
+ - You can set the version number explicitly when running sbt commands
+ - eg `sbt "set ThisBuild / version := \"1.0.0\"; sourceDistGenerate"`
+ - Or you can add a file called `version.sbt` to the same directory that has the `build.sbt` containing something like
+ - `ThisBuild / version := "1.0.0"`
+
+## Community
If you have questions about the contribution process or discuss specific issues, please interact with the community using the following resources.
- [GitHub discussions](https://github.com/apache/incubator-pekko-http/discussions): for questions and general discussion.
+- [Pekko users mailing list](https://lists.apache.org/list.html?users@pekko.apache.org): for Pekko development discussions.
- [Pekko dev mailing list](https://lists.apache.org/list.html?dev@pekko.apache.org): for Pekko development discussions.
- [GitHub issues](https://github.com/apache/incubator-pekko-http/issues): for bug reports and feature requests. Please search the existing issues before creating new ones. If you are unsure whether you have found a bug, consider asking in GitHub discussions or the mailing list first.
@@ -49,8 +79,8 @@ If you have questions about the contribution process or discuss specific issues,
[scaladex-projects]: https://index.scala-lang.org/search?q=dependencies:pekko/pekko-http*
-->
-Contributing
-------------
+## Contributing
+
Contributions are *very* welcome!
If you see an issue that you'd like to see fixed, the best way to make it happen is to help out by submitting a pull request.
@@ -60,7 +90,6 @@ Refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for more details about the
and general hints on how to prepare your pull request. You can also ask for clarifications or guidance in GitHub issues directly.
-License
--------
+## License
Apache Pekko HTTP is Open Source and available under the Apache 2 License.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org