Improve documentation #708

tindzk · 2017-05-07T13:34:02Z

A couple of suggestions for further improvements:

We should mention that Scala Native is garbage-collected and uses the Boehm GC. Does it make sense to include it as a core feature in index.rst?
We should have a section on compatibility with Scala JVM, notably which features are not supported yet.
The qualified native.<Type> access slightly impairs the reading flow. We could mention that all examples expect a prior import scala.scalanative.native._.
Using dots in enumerations is not very common and in some cases may add some confusion (see "Compilation modes" on the sbt page). I would suggest to remove them everywhere.

We should mention it in a separate chapter that Scala Native uses Clang.

jonas · 2017-05-07T14:48:31Z

docs/user/setup.rst

-* installation of LLVM and Clang
-* installation of Boehm GC
+* Java 8 or later
+* sbt 0.13.15


The sbt version doesn't really matter, since sbt will load the one defined in project/build.properties.

Yes, that's true. What do you think about removing the mention of project/build.properties from the sbt chapter? If we specify it in the setup chapter, it would be redundant.

The project/build.properties file ensures that the build is reproducible across different system so it should always be created. http://www.scala-sbt.org/0.13/docs/Basic-Def.html#Specifying+the+sbt+version

jonas · 2017-05-07T14:48:38Z

docs/user/setup.rst


-Installing LLVM, Clang and Boehm GC
-----------------------------------
+LLVM and Boehm GC are Scala Native's only external dependencies. Here are


I've also worked on updating this section to reflect that the Scala Native runtime and JDK implementation now depends on both Boehm GC and the RE2 regular expression engine.

https://github.com/scala-native/scala-native/pull/706/files#diff-a2d0368ffcd2931da4849e9d4288854e

Great work, BTW 👍

Ah, I didn't see your pull request. Let's get yours merged first, then I'll resolve any conflicts on my end.

Yep, lets merge @jonas' PR first, it's a bit smaller.

Duhemm

Thanks, that's a great improvement!

In the section Finding the right signature, it may be interesting to add something about getting POSIX signatures right. For instance, look at types.h. It re-defines some of the types specified by POSIX to use the largest type that we encounter in macOS or Linux, and structs that use these types must be re-defined to use the new definitions, as in stat.c for instance.

I can take care of that last part if you prefer.

Duhemm · 2017-05-09T07:50:09Z

docs/user/interop.rst

+C compilers typically require to pass an additional ``-l mylib`` flag to
+dynamically link with a library. In Scala Native, one can annotate libraries to
+link with using the ``@native.link`` annotation. As in C, it takes the library
+name without the ``lib`` prefix.


As in C, it takes the library name without the lib prefix.

I'm not sure this sentence makes things much clearer. I got a bit confused because lib is a suffix in the example above, plus this is not always true (take for instance zlib, you need to pass -l z to the linker). Maybe just say that you have to put whatever you would give your C compiler? I'm not a native English speaker, so that's really just a suggestion.

Thanks! This was in reference to libuv, which becomes -luv (later in the section there is an example with it). I will rephrase this sentence to make it clearer.

densh · 2017-05-09T09:33:23Z

Please rebase on top latest master due to conflicting docs changes.

tindzk · 2017-05-14T13:17:28Z

@Duhemm It is a good idea to mention this approach somewhere in the documentation, but I would suggest to do this in a separate chapter (or section) instead. From my understanding, this is only relevant for porting system libraries (such as POSIX). The end-user libraries I encountered all used platform-independent types such as size_t.

@densh I accidentally did a merge instead of a rebase. The conflicts were resolved.

densh · 2017-05-16T18:34:42Z

@Duhemm It would be indeed great to document that approach, but I have an impression this is out of scope of this PR. It mostly cleans up the content that we have now. Your suggested change should probably be addressed in subsequent iterations of the docs.

densh

See comments below.

densh · 2017-05-16T18:35:00Z

docs/user/setup.rst

-* installation of LLVM and Clang
-* installation of native libraries
+* Java 8
+* sbt


It would be good to mention version here, i.e. sbt 0.13.x

densh · 2017-05-16T18:35:06Z

docs/user/setup.rst

-* installation of native libraries
+* Java 8
+* sbt
+* LLVM 3.7


3.7 or newer.

densh · 2017-05-16T18:35:11Z

docs/user/setup.rst

-* installation of sbt
-* installation of LLVM and Clang
-* installation of native libraries
+* Java 8


Java 8 or newer.

I wrote in the paragraph before "Scala Native has the following minimum system requirements". Should I still add "or newer" for clarity?

I'd say it would be more clear to write Java 8+ or something along those lines.

densh · 2017-05-16T18:36:18Z

docs/user/setup.rst

+  relocation R_X86_64_32 against `.rodata.str1.1' can not be used when making a shared object; recompile with -fPIC
+
+It is likely that the ``LDFLAGS`` environment variable enables hardening. For example, this occurs when the ``hardening-wrapper`` package is installed on Arch Linux. It can be safely removed.
+


I have an impression that this one deserves to be on the same page together with FAQ, given that we don't expect many people to hit this problem

densh · 2017-05-17T15:15:34Z

LGTM, thanks for the clean up! 😄 👍

tindzk · 2017-05-17T18:29:22Z

Great, thanks a lot! Do you have any comments to my suggestions from the first post?

densh · 2017-05-18T09:28:27Z

Regarding GC: we're going to have a new garbage collector soon, we'll probably put into highlights on the first page once it happens. :)
Regarding compatibility: we have javalib and language pages, the combinations of the two should give a reasonable impression of what's there and what's not.
Regarding having an import: I am not 100% convinced, but I understand the idea. We can do it if you feel like it's going to improve the docs for newcomers.
Dots in enumeration: sure, lets change that.

* docs: Fix spelling of Nix and NixOS * docs: Improve formatting of operating systems * docs: Use `apt` instead of `apt-get` on Ubuntu * docs: Fix sbt instructions * docs: Use inline literals in interoperability table * docs: Use footnotes in interoperability table * docs: Add instructions for Arch Linux * docs: Improve wording in environment setup We should mention it in a separate chapter that Scala Native uses Clang. * docs: Add missing section on function pointers * docs: Improve section on linking * docs: Don't specify sbt version * docs: Rephrase remark about `lib` prefix * docs: Fix preposition on interoperability page * docs: Add missing types to interoperability table * docs: Improve wording of section on unchecked casts * docs: Add section on platform-specific types * docs: Add section on determining the size of types * docs: Specify version for sbt * docs: Move section on troubleshooting to FAQ * docs: Fix enumeration on sbt page * docs: Improve punctuation and grammar on sbt page * docs: Clarify version numbers

tindzk added 10 commits May 7, 2017 13:15

docs: Fix spelling of Nix and NixOS

48b3119

docs: Improve formatting of operating systems

fb008fb

docs: Use apt instead of apt-get on Ubuntu

41e3fb6

docs: Fix sbt instructions

0e637ab

docs: Use inline literals in interoperability table

a0486d7

docs: Use footnotes in interoperability table

b3632bc

docs: Add instructions for Arch Linux

59562ac

docs: Improve wording in environment setup

d4c3750

We should mention it in a separate chapter that Scala Native uses Clang.

docs: Add missing section on function pointers

9821f61

docs: Improve section on linking

1a3c06d

jonas reviewed May 7, 2017

View reviewed changes

docs: Don't specify sbt version

c43aaee

Duhemm suggested changes May 9, 2017

View reviewed changes

tindzk added 7 commits May 10, 2017 23:30

Merge branch 'master' into docs

271fa8f

docs: Rephrase remark about lib prefix

57304e4

docs: Fix preposition on interoperability page

c54d798

docs: Add missing types to interoperability table

bc46024

docs: Improve wording of section on unchecked casts

e9a08e6

docs: Add section on platform-specific types

a10452e

docs: Add section on determining the size of types

fd23a66

densh requested changes May 16, 2017

View reviewed changes

tindzk added 5 commits May 17, 2017 12:53

docs: Specify version for sbt

e682333

docs: Move section on troubleshooting to FAQ

e9cee5b

docs: Fix enumeration on sbt page

2c5fd24

docs: Improve punctuation and grammar on sbt page

9418cfb

docs: Clarify version numbers

15de238

densh approved these changes May 17, 2017

View reviewed changes

densh merged commit d034230 into scala-native:master May 17, 2017

tindzk deleted the docs branch May 17, 2017 18:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation #708

Improve documentation #708

tindzk commented May 7, 2017 •

edited

jonas May 7, 2017

tindzk May 7, 2017

jonas May 7, 2017

jonas May 7, 2017

tindzk May 7, 2017

densh May 9, 2017

Duhemm left a comment

Duhemm May 9, 2017

tindzk May 9, 2017

densh commented May 9, 2017

tindzk commented May 14, 2017

densh commented May 16, 2017

densh left a comment

densh May 16, 2017

densh May 16, 2017

densh May 16, 2017

tindzk May 17, 2017

densh May 17, 2017 •

edited

densh May 16, 2017 •

edited

densh commented May 17, 2017

tindzk commented May 17, 2017

densh commented May 18, 2017

		relocation R_X86_64_32 against `.rodata.str1.1' can not be used when making a shared object; recompile with -fPIC

		It is likely that the ``LDFLAGS`` environment variable enables hardening. For example, this occurs when the ``hardening-wrapper`` package is installed on Arch Linux. It can be safely removed.

Improve documentation #708

Improve documentation #708

Conversation

tindzk commented May 7, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Duhemm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

densh commented May 9, 2017

tindzk commented May 14, 2017

densh commented May 16, 2017

densh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

densh May 17, 2017 • edited

Choose a reason for hiding this comment

densh May 16, 2017 • edited

Choose a reason for hiding this comment

densh commented May 17, 2017

tindzk commented May 17, 2017

densh commented May 18, 2017

tindzk commented May 7, 2017 •

edited

densh May 17, 2017 •

edited

densh May 16, 2017 •

edited