-
Notifications
You must be signed in to change notification settings - Fork 361
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add contributing quickstart guide #3496
Changes from all commits
fd542a2
a82a1ee
b17677f
fcb9df6
1e57fea
5ce4b22
57b7c44
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,6 +6,7 @@ Contributor's Guide | |
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
quickstart | ||
contributing | ||
build | ||
compiler | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,134 @@ | ||
.. _quickstart: | ||
|
||
Quick Start Guide | ||
================= | ||
|
||
Document built: |today| | ||
|
||
Requirements | ||
------------ | ||
|
||
- Java 8 or newer | ||
- LLVM/Clang 15 or newer | ||
- sbt | ||
|
||
Project Structure Overview | ||
-------------------------- | ||
|
||
See :ref:`build` | ||
|
||
Project suffix | ||
-------------- | ||
|
||
Most projects in ScalaNative cross-build against Scala ``2.12``, ``2.13`` and ``3``, and these projects have a suffix like ``2_12``, ``2_13`` or ``3`` to differentiate the Scala version. | ||
For example, ``sandbox`` has ``sandbox2_12``, ``sandbox2_13`` and ``sandbox3``. | ||
|
||
In the following we will use suffix ``3``, but remember that you can build and test for different versions using different suffixes. | ||
|
||
Build / Manual Testing on Sandbox | ||
--------------------------------- | ||
|
||
``sandbox3/run`` to compile, link and run the main method of the sandbox project defined in ``sandbox/src/main/scala/Test.scala``. | ||
|
||
It's convenient to run the ``sandbox`` project to verify the build works as expected. | ||
|
||
Test | ||
---- | ||
|
||
**Common Test Commands** | ||
|
||
- ``tests3/test`` - run the unit tests for libraries on native build | ||
- ``tests3/testOnly org.scalanative.testsuite.javalib.util.RandomTest`` - run only the test of interest | ||
- ``tests3/testOnly *.RandomTest`` - run only the test of interest using wildcard | ||
- ``testsExt3/test`` - run the unit tests on native build, this module contains tests that requires dummy javalib implementation defined in ``javalibExtDummies``. | ||
- ``nirJVM3/test`` - run the unit tests for NIR | ||
- ``toolsJVM3/test`` - run the unit tests of the tools: ScalaNative backend | ||
- ``sbtScalaNative/scripted`` - run all `scripted tests <https://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html>`_ of the sbt plugin (this takes a while). | ||
- ``sbtScalaNative/scripted <test directory to run>`` - run specific scripted tests of the sbt plugin. e.g. ``sbtScalaNative/scripted run/backtrace`` | ||
- Scripted tests are used when you need to interact with the file system, networking, or the build system that cannot be done with a unit test. | ||
- ``set ThisBuild / scriptedBufferLog := false`` disables buffer log in scripted test and get more verbose output | ||
|
||
**Other Test Commands** | ||
|
||
- ``testsJVM3/test`` - run ``tests3/test`` on JVM | ||
- ``testsExtJVM3/test`` - run ``testsExt3/test`` on JVM | ||
- ``test-all`` - run all tests, ideally after ``reload`` and ``clean`` | ||
|
||
**Some additional tips** | ||
|
||
- If you modify the ``nscplugin``, you will need to ``clean`` the project that | ||
you want to rebuild with its new version (typically ``sandbox/clean`` or | ||
``tests/clean``). For a full rebuild, use the global ``clean`` command. | ||
|
||
- If you modify the sbt plugin or any of its transitive dependencies | ||
(``sbt-scala-native``, ``nir``, ``util``, ``tools``, ``test-runner``), you | ||
will need to ``reload`` for your changes to take effect with most test | ||
commands (except with the ``scripted`` tests). | ||
|
||
- For a completely clean build, from scratch, run ``reload`` *and* ``clean``. | ||
|
||
Formatting | ||
---------- | ||
|
||
- ``./scripts/scalafmt`` - format all Scala codes | ||
- ``./scripts/clangfmt`` - format all C/C++ codes | ||
|
||
`Publish Locally <https://www.scala-sbt.org/1.x/docs/Publishing.html>`_ | ||
----------------------------------------------------------------------- | ||
|
||
``publish-local-dev x.y.z`` publishes the ScalaNative artifact and sbt plugin for specified scala version locally. | ||
For example, ``publish-local-dev 3.3.1``, | ||
|
||
You will see, the log message like the following, which means you have successfully published locally for the version ``0.5.0-SNAPSHOT``. | ||
|
||
.. code-block:: text | ||
|
||
[info] published tools_native0.5.0-SNAPSHOT_3 to ... | ||
[info] published ivy to ...tools_native0.5.0-SNAPSHOT_3/0.5.0-SNAPSHOT/ivys/ivy.xml | ||
|
||
Then you'll be able to use locally published version in other projects. | ||
|
||
.. code-block:: text | ||
|
||
# project/plugins.sbt | ||
addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.5.0-SNAPSHOT") | ||
|
||
# build.sbt | ||
scalaVersion := "3.3.1" # set to locally published version | ||
enablePlugins(ScalaNativePlugin) | ||
|
||
Locally build docs | ||
-------------------- | ||
|
||
1. First time building the docs. This command will setup & build the docs. | ||
|
||
.. code-block:: text | ||
|
||
$ bash scripts/makedocs setup | ||
|
||
2. If setup is already done. This command will only build the docs assuming setup is already done. | ||
|
||
.. code-block:: text | ||
|
||
$ bash scripts/makedocs | ||
|
||
3. Navigate to ``docs/_build/html`` directory and open ``index.html`` file in your browser. | ||
|
||
Configure Native Build | ||
---------------------- | ||
|
||
To configure the native build in this project, you can edit ``project/MyScalaNativePlugin.scala`` instead of ``project/Build.scala``. | ||
|
||
``MyScalaNativePlugin`` is a custom sbt plugin that extends ``ScalaNativePlugin`` and overrides some of its settings for this project. | ||
|
||
|
||
Further Information | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should add parapgrah about modifing default There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. added fcb9df6 |
||
------------------- | ||
|
||
- How to make a commit and PR :ref:`contributing` | ||
- More detailed build setting explanation :ref:`build` | ||
- Scala Native Internal | ||
- :ref:`compiler` | ||
- :ref:`nir` | ||
- :ref:`name_mangling` | ||
- How to setup IDEs :ref:`ides` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One thing I have noticed is that reloading will reset the version of Scala you might have configured when you started sbt.
I might be doing something wrong but that definitely was a surprise for me. Maybe it deserves a mention in this guide.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's more like sbt usage?
$ sbt
to launch sbt shell, no need for++x.y.z
andshell
I'm not sure we should add explanation for that here.
And do we want to document
test-all
, since it takes so long and I personally never used in my local development.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, I understand.
I think I would still add something like "remember that
reload
will cause the session to be restarted fresh, meaning that your configurations (e.g.,++3.3.0
) will be reset as well."And thanks for the explanations, by the way ;)
I think we should. FWIW, the first thing I always try to do when I get started with an open source project is to try running the most comprehensive test suite possible.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it is better to point to something a little less comprehensive to start like
tests3/test
or the tools test. ThetestsJVM
will run tests against the VM so the is good to mention forjavalib
. You might want to mention the 2_13 and 2_12 versions as well. We can't assume we have sbt experts.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hear you but my two cents is that I still believe that there should be a way for someone cloning SN for the first time to make sure everything works as expected, even if
test-all
is a command that's almost never run in the "standard development workflow".There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You are correct but this is very much a WIP and we may have failures especially with new versions of software or different platforms - what we are trying to do is hard and 0.5.0 has not really settled down 100%.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, I understand.
If we can agree that the goal is to eventually be able to run
test-all
on supported platforms, why not keep a brief record of this discussion in the docs for the next me? I would suggest something like this:There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just added a disclaimer that
test-all
may fail 1e57feaI hope someone who know more about test-all can update the sentence later.