chrisj at rtems.org
Thu Jan 17 05:45:58 UTC 2019
On 14/1/19 5:36 pm, Sebastian Huber wrote:
> I added a build of the partially restructured user manual here:
As an aside in the copyright block I wrote of lot of initial parts of this
manual and then have been adding pieces most years including 2018. How do the
year lists work?
> On 13/01/2019 23:03, Chris Johns wrote:
>> On 11/1/19 8:13 pm, Sebastian Huber wrote:
>>> At which position in the manual should it be placed? I think we should
>>> organize the chapters according to the relevance for new users and how the
>>> are used later during application development. I would use the RSB chapter as
>>> a reference chapter containing all the details and cover the common case in
>>> the Quick Start chapter. So, I would move the RSB chapter to the end after
>>> the Host Tools.
>> The place the RSB moves to could depend on where some others get moved too. A
>> review of the sections follows.
>> Do we need a "How to use this manual?" section in the Introduction? It could
>> also have a "What to read before starting" part.
> I think this should go into Introduction -> Overview.
Yes I agree and also each major section should have something.
>> The manual is organised as:
>> Overview, features, what a real-time and what a real-time kernel is.
>> Rational, open source and deployment. This is to explain what we
>> call the host side tools, commands, and configuration. Maybe we
>> need to explain RTEMS is only run on targets and is not self
>> hosting so the ecosystem provides a consistent host side
>> This section needs to be enhanced to cover the RSB, RTEMS Tools
>> and what ever else we want to include. The deployment section's
>> building binary tools can be moved to some where else, that is
>> an advanced topic.
> I moved the Ecosystem into Introduction, since it introduces the RTEMS world. I
> think it fits quite well here.
Nice and yes I agree.
>> Quick Start
>> I think we need to keep a top level section called "Quick Start"
>> because it is easy for a new user to see and click on. The sidebar
>> on the html output is collapsed and searching for a quick start or
>> something like it is awkward. Links to other sections should aim to
>> provide launch sites to more detail.
> Yes, this is now the second chapter. I would like to use the following sections:
> "Host Computer Setup"
> "RTEMS Repository Clone"
> "RTEMS Tool Set Installation"
> "RTEMS Source Bootstrap"
> "BSP Configuration and Installation"
> "Example Application"
> Do we want to use "tool chain" or "tool set" or "tools" for the RTEMS things
> running on the host computer?
Yeah good question. A "tool chain" seems to have a meaning, a compile etc, a
"tool set" is an RSB based term and "tools" is overloaded with the rtems-tools.
I suppose to have a host tool suite? For example, the first sentence from the
"This section details how to set up and install the RTEMS Ecosystem.
You will create a tools suite for your host compiler and an RTEMS kernel
for your selected Board Support Package (BSP)."
>> Host Computer
>> Should this be placed under Ecosystem?
>> This needs to be before the RSB section so the correct packages are
>> present on the host for the RSB.
> I think this should remain a separate chapter. It is one of the first things you
> have to deal with as a new user.
>> This explains the environment. Is this also part of the Ecosystem?
> The installation of things running on the host and the installation of an RTEMS
> BSP should be in separate chapters.
>> A discussion about the way RTEMS views hardware, architectures and
>> BSPs. This is about the RTEMS side of things rather than the
>> host and the ecosystem.
>> Board Support Packages
>> The BSPs. I have been wondering if the BSP names are suitable
>> heading or do we want something more formal if that is even
> The heading is now "<BSP family directory name> (<product marketing name>)".
> This should make it easy to find.
Hmm I am not sure, for some reason it looks and feel incomplete, needing more
work because the heading are not formal. For example 'i386' would look better
>> This is the first section I have added that starts with something
>> about the section and what to expect. I think this is a good
>> practice to do.
>> I am planning to add a section on libdl and applications for it
>> once the rtl-archive and rtl-ctor-dtor branches in
>> https://git.rtems.org/chrisj/rtems.git/ are merged.
>> Using the rtems-test and rtems-run interface to run code.
>> The tracing support for RTEMS. This is the last in a progression
>> from a host, tools, kernel, testing the kernel, to runtime performance.
>> Host Tools
>> The published interface to the tools we support. In effect the interface
>> users can depend on across releases.
>> I hope this helps.
>> Note: I see the index is broken with the online builds. I suspect the
>> genindex.rst removal I did is the cause and I also suspect there is an issue
>> between versions of sphinx-build being used. My development version is newer
>> than the online builder but we cannot update that version until the xindy issue
>> on FreeBSD is resolved and even with upstream FreeBSD fixing the port getting it
>> into the version 10 we run is problematic.
> It is also broken on my host. I use sphinx-build 1.8.1.
I suspect your texlive has a working xindy which is better than mine. I have
emailed the tex port maintainer and heard nothing back and the tex port lists
seem dormant. The FreeBSD Tex on 12-RELEASE is 2015 and that verison pre-dates
the xindy command. It is a bit of a mess.
More information about the devel