NaCl documentation: improve building documentation

NaCl documentation: improve building documentation

R= dschuff@chromium.org
TEST=none
BUG=none
NOTRY=true
(documentation only change)

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=279757

[Derek Schuff, 2014-06-24 18:33:42]

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
did you mean to remove "any" here?
Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS processors"

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:80: access non-standard
extensions which newlib often relies on).
I assume this is a response to the recent reports about build failures? I wonder
if its worth making gnu++11 the primary recommendation since a lot of code from
the posix world just assumes gnu extensions (including newlib) Similarly to how
the default C and C++ standards are gnu.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:245: ``-O3`` for
profiling and deployment.
maybe we shouldn't refer to profiling if there's no useful way to actually do
it.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:255: increase the size
of a **pexe** may not increase the size of the compressed
maybe even make it a little more clear and say "Optimizations that increase the
size of the uncompressed pexe". Also "very much" sounds better than "that much"

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:267: size and on-device
translation speed.
Mention that the particular value of 5 turns the inliner way down. Not sure if
it's worth mentioning that the default is 225. Maybe even make it 'n' as in On

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:373: by most web
servers as part of HTTP compression. This compression step is in
This seems to imply that the compression is automatic, although the next
sentence implies that gzipping for deployment is something the developer would
do. I guess it depends on the server configuration, maybe we could make that
more clear.

[binji, 2014-06-24 20:51:48]

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:267: size and on-device
translation speed.
On 2014/06/24 18:33:42, Derek Schuff wrote:
> Mention that the particular value of 5 turns the inliner way down. Not sure if
> it's worth mentioning that the default is 225. Maybe even make it 'n' as in On

Agreed, I wouldn't have guessed the valid range would be so large.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:308: and on-device
translation.
We have an example link line for debug, maybe it would be good to add one for
release too (including -O2)

[JF, 2014-06-25 01:27:47]

Updated, PTAL.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
On 2014/06/24 18:33:42, Derek Schuff wrote:
> did you mean to remove "any" here?
> Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS processors"

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:80: access non-standard
extensions which newlib often relies on).
On 2014/06/24 18:33:42, Derek Schuff wrote:
> I assume this is a response to the recent reports about build failures? I
wonder
> if its worth making gnu++11 the primary recommendation since a lot of code
from
> the posix world just assumes gnu extensions (including newlib) Similarly to
how
> the default C and C++ standards are gnu.

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:245: ``-O3`` for
profiling and deployment.
On 2014/06/24 18:33:42, Derek Schuff wrote:
> maybe we shouldn't refer to profiling if there's no useful way to actually do
> it.

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:255: increase the size
of a **pexe** may not increase the size of the compressed
On 2014/06/24 18:33:42, Derek Schuff wrote:
> maybe even make it a little more clear and say "Optimizations that increase
the
> size of the uncompressed pexe". Also "very much" sounds better than "that
much"

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:267: size and on-device
translation speed.
On 2014/06/24 18:33:42, Derek Schuff wrote:
> Mention that the particular value of 5 turns the inliner way down. Not sure if
> it's worth mentioning that the default is 225. Maybe even make it 'n' as in On

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:308: and on-device
translation.
On 2014/06/24 20:51:47, binji wrote:
> We have an example link line for debug, maybe it would be good to add one for
> release too (including -O2)

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:373: by most web
servers as part of HTTP compression. This compression step is in
On 2014/06/24 18:33:42, Derek Schuff wrote:
> This seems to imply that the compression is automatic, although the next
> sentence implies that gzipping for deployment is something the developer would
> do. I guess it depends on the server configuration, maybe we could make that
> more clear.

Done.

[Derek Schuff, 2014-06-25 17:27:02]

otherwise LGTM

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
On 2014/06/25 01:27:46, JF wrote:
> On 2014/06/24 18:33:42, Derek Schuff wrote:
> > did you mean to remove "any" here?
> > Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS processors"
> 
> Done.
Now it says "will run on processor x86-32 ..."

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:80: access non-standard
extensions which newlib often relies on).
On 2014/06/25 01:27:46, JF wrote:
> On 2014/06/24 18:33:42, Derek Schuff wrote:
> > I assume this is a response to the recent reports about build failures? I
> wonder
> > if its worth making gnu++11 the primary recommendation since a lot of code
> from
> > the posix world just assumes gnu extensions (including newlib) Similarly to
> how
> > the default C and C++ standards are gnu.
> 
> Done.

saying that newlib relies on gnu extensions rather than isn't always compatible
might make it sound a little more positive.

[JF, 2014-06-25 17:44:01]

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
On 2014/06/25 17:27:02, Derek Schuff wrote:
> On 2014/06/25 01:27:46, JF wrote:
> > On 2014/06/24 18:33:42, Derek Schuff wrote:
> > > did you mean to remove "any" here?
> > > Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS
processors"
> > 
> > Done.
> Now it says "will run on processor x86-32 ..."

Done.

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:80: access non-standard
extensions which newlib often relies on).
On 2014/06/25 17:27:02, Derek Schuff wrote:
> On 2014/06/25 01:27:46, JF wrote:
> > On 2014/06/24 18:33:42, Derek Schuff wrote:
> > > I assume this is a response to the recent reports about build failures? I
> > wonder
> > > if its worth making gnu++11 the primary recommendation since a lot of code
> > from
> > > the posix world just assumes gnu extensions (including newlib) Similarly
to
> > how
> > > the default C and C++ standards are gnu.
> > 
> > Done.
> 
> saying that newlib relies on gnu extensions rather than isn't always
compatible
> might make it sound a little more positive.

Done.

[binji, 2014-06-25 17:58:15]

lgtm

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
On 2014/06/25 17:44:01, JF wrote:
> On 2014/06/25 17:27:02, Derek Schuff wrote:
> > On 2014/06/25 01:27:46, JF wrote:
> > > On 2014/06/24 18:33:42, Derek Schuff wrote:
> > > > did you mean to remove "any" here?
> > > > Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS
> processors"
> > > 
> > > Done.
> > Now it says "will run on processor x86-32 ..."
> 
> Done.

processors :)

[JF, 2014-06-25 18:03:04]

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
File native_client_sdk/src/doc/devguide/devcycle/building.rst (right):

https://codereview.chromium.org/356573003/diff/1/native_client_sdk/src/doc/de...
native_client_sdk/src/doc/devguide/devcycle/building.rst:33: will run on
Windows, Mac OS X, Linux, and ChromeOS and it will run on processor
On 2014/06/25 17:58:15, binji wrote:
> On 2014/06/25 17:44:01, JF wrote:
> > On 2014/06/25 17:27:02, Derek Schuff wrote:
> > > On 2014/06/25 01:27:46, JF wrote:
> > > > On 2014/06/24 18:33:42, Derek Schuff wrote:
> > > > > did you mean to remove "any" here?
> > > > > Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS
> > processors"
> > > > 
> > > > Done.
> > > Now it says "will run on processor x86-32 ..."
> > 
> > Done.
> 
> processors :)

Dones.

[JF, 2014-06-25 18:08:57]

The CQ bit was checked by jfb@chromium.org

[commit-bot: I haz the power, 2014-06-25 18:10:15]

CQ is trying da patch. Follow status at
 https://chromium-status.appspot.com/cq/jfb@chromium.org/356573003/60001

[commit-bot: I haz the power, 2014-06-25 18:15:11]

Change committed as 279757