From c0982900e96713381862b7c50da7ad892c80ff26 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 11 Jan 2019 12:54:20 +0100 Subject: user: Move "Ecosystem" into "Introduction" --- user/ecosys/index.rst | 240 ------------------------------------------------ user/index.rst | 2 - user/overview/index.rst | 239 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 239 insertions(+), 242 deletions(-) delete mode 100644 user/ecosys/index.rst diff --git a/user/ecosys/index.rst b/user/ecosys/index.rst deleted file mode 100644 index 201cda3..0000000 --- a/user/ecosys/index.rst +++ /dev/null @@ -1,240 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2016 Chris Johns - -.. _ecosystem: - -Ecosystem -********* -.. index:: Ecosystem - -The RTEMS Ecosystem is the collection of tools, packages, code, documentation -and online content provided by the RTEMS Project. The ecosystem provides a way -to develop, maintain, and use RTEMS. It's parts interact with the user, the -host environment, and each other to make RTEMS accessible, useable and -predicable. - -The ecosystem is for users, developers and maintainers and it is an ongoing -effort that needs your help and support. The RTEMS project is always improving -the way it delivers the kernel to you and your feedback is important so please -join the mailing lists and contribute back comments, success stories, bugs and -patches. - -What the RTEMS project describes here to develop, maintain and use RTEMS does -not dictate what you need to use in your project. You can and should select the -work-flow that best suites the demands of your project and what you are -delivering. - -Rational -======== - -RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the -complexity for users by providing a stable documented way to build, configure -and run RTEMS. RTEMS is more than a kernel running real-time applications on -target hardware, it is part of a project's and therefore team's workflow and -every project and team is different. - -RTEMS's ecosystem does not mandate a way to work. It is a series of parts, -components, and items that are used to create a suitable development -environment to work with. The processes explained in this manual are the same -things an RTEMS maintainer does to maintain the kernel or an experienced user -does to build their production system. It is important to keep this in mind -when working through this manual. We encourage users to explore what can be -done and to discover ways to make it fit their needs. The ecosystem provided by -the RTEMS Project will not install in a single click of a mouse because we want -users to learn the parts they will come to depend on as their project's -development matures. - -The RTEMS Ecosystem provides a standard interface that is the same on all -supported host systems. Standardizing how a user interacts with RTEMS is -important and making that experience portable is also important. As a result -the ecosystem is documented at the command line level and we leave GUI and IDE -integration for users and integrators. - -Standardizing the parts and how to use them lets users create processes and -procedures that are stable over releases. The RTEMS Ecosystem generates data -that can be used to audit the build process so their configuration can be -documented. - -The ecosystem is based around the source code used in the various parts, -components and items of the RTEMS development environment. A user can create -an archive of the complete build process including all the source code for long -term storage. This is important for projects with a long life cycle. - -Open Source -=========== - -RTEMS is an open source operating system and an open source project and this -extends to the ecosystem. We encourage users to integrate the processes to -build tools, the kernel and any 3rd party libraries into their project's -configuration management processes. - -All the parts that make up the ecosystem are open source. The ecosystem uses a -package's source code to create an executable on a host so when an example -RTEMS executable is created and run for the first time the user will have built -every tool as well as the executable from source. The RTEMS Project believes -the freedom this gives a user is as important as the freedom of having access -to the source code for a package. - -Deployment -========== - -The RTEMS Project provides the ecosystem as source code that users can download -to create personalised development environments. The RTEMS Project does not -provide packaging and deployment for a specific host environment, target -architecture or BSP. The RTEMS Project encourages users and organizations to -fill this role for the community. - -Building and Deploying Tool Binaries ------------------------------------- - -If you wish to create and distribute your build or you want to archive a build -you can create a tar file. We term this deploying a build. This is a more -advanced method for binary packaging and installing of tools. - -By default the RTEMS Source Builder installs the built packages directly and -optionally it can also create a *build set tar file* or a *package tar file* -per package built. The normal and default behaviour is to let the RTEMS Source -Builder install the tools. The source will be downloaded, built, installed and -cleaned up. - -The tar files are created with the full build prefix present and if you follow -the examples given in this documentation the path is absolute. This can cause -problems if you are installing on a host you do not have super user or -administrator rights on because the prefix path may references part you do not -have write access too and tar will not extract the files. You can use the -``--strip-components`` option in tar if your host tar application supports it -to remove the parts you do not have write access too or you may need to unpack -the tar file somewhere and copy the file tree from the level you have write -access from. Embedding the full prefix path in the tar files lets you know what -the prefix is and is recommended. For example if -``/home/chris/development/rtems/4.11`` is the prefix used you cannot change -directory to the root (``/``) and untar the file because the ``/home`` is root -access only. To install a tar file you have downloaded into your new machine's -``Downloads`` directory in your home directoty you would enter: - -.. code-block:: shell - - $ cd /somewhere - $ tar --strip-components=3 -xjf \ - $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2 - -A build set tar file is created by adding ``--bset-tar-file`` option to the -``sb-set-builder`` command:: - - $ ../source-builder/sb-set-builder --log=l-sparc.txt \ - --prefix=$HOME/development/rtems/4.11 \ - --bset-tar-file \ <1> - 4.11/rtems-sparc - Source Builder - Set Builder, v0.2.0 - Build Set: 4.11/rtems-sparc - config: expat-2.1.0-1.cfg - package: expat-2.1.0-x86_64-freebsd9.1-1 - building: expat-2.1.0-x86_64-freebsd9.1-1 - config: tools/rtems-binutils-2.22-1.cfg - package: sparc-rtems4.11-binutils-2.22-1 - building: sparc-rtems4.11-binutils-2.22-1 - config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg - package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - config: tools/rtems-gdb-7.5.1-1.cfg - package: sparc-rtems4.11-gdb-7.5.1-1 - building: sparc-rtems4.11-gdb-7.5.1-1 - installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2> - installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 - installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 - installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 - tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> - cleaning: expat-2.1.0-x86_64-freebsd9.1-1 - cleaning: sparc-rtems4.11-binutils-2.22-1 - cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - cleaning: sparc-rtems4.11-gdb-7.5.1-1 - Build Set: Time 0:15:25.92873 - -.. topic:: Items - - 1. The option to create a build set tar file. - - 2. The installation still happens unless you specify ``--no-install``. - - 3. Creating the build set tar file. - -You can also suppress installing the files using the ``--no-install`` -option. This is useful if your prefix is not accessiable, for example when -building Canadian cross compiled tool sets:: - - $ ../source-builder/sb-set-builder --log=l-sparc.txt \ - --prefix=$HOME/development/rtems/4.11 \ - --bset-tar-file \ - --no-install \ <1> - 4.11/rtems-sparc - Source Builder - Set Builder, v0.2.0 - Build Set: 4.11/rtems-sparc - config: expat-2.1.0-1.cfg - package: expat-2.1.0-x86_64-freebsd9.1-1 - building: expat-2.1.0-x86_64-freebsd9.1-1 - config: tools/rtems-binutils-2.22-1.cfg - package: sparc-rtems4.11-binutils-2.22-1 - building: sparc-rtems4.11-binutils-2.22-1 - config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg - package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - config: tools/rtems-gdb-7.5.1-1.cfg - package: sparc-rtems4.11-gdb-7.5.1-1 - building: sparc-rtems4.11-gdb-7.5.1-1 - tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2> - cleaning: expat-2.1.0-x86_64-freebsd9.1-1 - cleaning: sparc-rtems4.11-binutils-2.22-1 - cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - cleaning: sparc-rtems4.11-gdb-7.5.1-1 - Build Set: Time 0:14:11.721274 - $ ls tar - rtems-4.11-sparc-rtems4.11-1.tar.bz2 - -.. topic:: Items - - 1. The option to supressing installing the packages. - - 2. Create the build set tar. - -A package tar file can be created by adding the ``--pkg-tar-files`` to the -``sb-set-builder`` command. This creates a tar file per package built in the -build set:: - - $ ../source-builder/sb-set-builder --log=l-sparc.txt \ - --prefix=$HOME/development/rtems/4.11 \ - --bset-tar-file \ - --pkg-tar-files \ <1> - --no-install 4.11/rtems-sparc - Source Builder - Set Builder, v0.2.0 - Build Set: 4.11/rtems-sparc - config: expat-2.1.0-1.cfg - package: expat-2.1.0-x86_64-freebsd9.1-1 - building: expat-2.1.0-x86_64-freebsd9.1-1 - config: tools/rtems-binutils-2.22-1.cfg - package: sparc-rtems4.11-binutils-2.22-1 - building: sparc-rtems4.11-binutils-2.22-1 - config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg - package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - config: tools/rtems-gdb-7.5.1-1.cfg - package: sparc-rtems4.11-gdb-7.5.1-1 - building: sparc-rtems4.11-gdb-7.5.1-1 - tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 - cleaning: expat-2.1.0-x86_64-freebsd9.1-1 - cleaning: sparc-rtems4.11-binutils-2.22-1 - cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 - cleaning: sparc-rtems4.11-gdb-7.5.1-1 - Build Set: Time 0:14:37.658460 - $ ls tar - expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2 - sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> - sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2 - -.. topic:: Items - - 1. The option to create packages tar files. - - 2. The GDB package tar file. - - 3. The build set tar file. All the others in a single tar file. diff --git a/user/index.rst b/user/index.rst index 1eda925..b61942e 100644 --- a/user/index.rst +++ b/user/index.rst @@ -26,8 +26,6 @@ RTEMS User Manual (|version|). :numbered: overview/index - ecosys/index - start/index hosts/index installation/index diff --git a/user/overview/index.rst b/user/overview/index.rst index a3718d2..f00ecdf 100644 --- a/user/overview/index.rst +++ b/user/overview/index.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2016 Chris Johns + Introduction ************ @@ -182,6 +184,243 @@ RTEMS provides the following basic feature set: - Support to stay in synchronization with FreeBSD +.. _ecosystem: + +Ecosystem +========= +.. index:: Ecosystem + +The RTEMS Ecosystem is the collection of tools, packages, code, documentation +and online content provided by the RTEMS Project. The ecosystem provides a way +to develop, maintain, and use RTEMS. It's parts interact with the user, the +host environment, and each other to make RTEMS accessible, useable and +predicable. + +The ecosystem is for users, developers and maintainers and it is an ongoing +effort that needs your help and support. The RTEMS project is always improving +the way it delivers the kernel to you and your feedback is important so please +join the mailing lists and contribute back comments, success stories, bugs and +patches. + +What the RTEMS project describes here to develop, maintain and use RTEMS does +not dictate what you need to use in your project. You can and should select the +work-flow that best suites the demands of your project and what you are +delivering. + +Rational +-------- + +RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the +complexity for users by providing a stable documented way to build, configure +and run RTEMS. RTEMS is more than a kernel running real-time applications on +target hardware, it is part of a project's and therefore team's workflow and +every project and team is different. + +RTEMS's ecosystem does not mandate a way to work. It is a series of parts, +components, and items that are used to create a suitable development +environment to work with. The processes explained in this manual are the same +things an RTEMS maintainer does to maintain the kernel or an experienced user +does to build their production system. It is important to keep this in mind +when working through this manual. We encourage users to explore what can be +done and to discover ways to make it fit their needs. The ecosystem provided by +the RTEMS Project will not install in a single click of a mouse because we want +users to learn the parts they will come to depend on as their project's +development matures. + +The RTEMS Ecosystem provides a standard interface that is the same on all +supported host systems. Standardizing how a user interacts with RTEMS is +important and making that experience portable is also important. As a result +the ecosystem is documented at the command line level and we leave GUI and IDE +integration for users and integrators. + +Standardizing the parts and how to use them lets users create processes and +procedures that are stable over releases. The RTEMS Ecosystem generates data +that can be used to audit the build process so their configuration can be +documented. + +The ecosystem is based around the source code used in the various parts, +components and items of the RTEMS development environment. A user can create +an archive of the complete build process including all the source code for long +term storage. This is important for projects with a long life cycle. + +Open Source +----------- + +RTEMS is an open source operating system and an open source project and this +extends to the ecosystem. We encourage users to integrate the processes to +build tools, the kernel and any 3rd party libraries into their project's +configuration management processes. + +All the parts that make up the ecosystem are open source. The ecosystem uses a +package's source code to create an executable on a host so when an example +RTEMS executable is created and run for the first time the user will have built +every tool as well as the executable from source. The RTEMS Project believes +the freedom this gives a user is as important as the freedom of having access +to the source code for a package. + +Deployment +---------- + +The RTEMS Project provides the ecosystem as source code that users can download +to create personalised development environments. The RTEMS Project does not +provide packaging and deployment for a specific host environment, target +architecture or BSP. The RTEMS Project encourages users and organizations to +fill this role for the community. + +Building and Deploying Tool Binaries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you wish to create and distribute your build or you want to archive a build +you can create a tar file. We term this deploying a build. This is a more +advanced method for binary packaging and installing of tools. + +By default the RTEMS Source Builder installs the built packages directly and +optionally it can also create a *build set tar file* or a *package tar file* +per package built. The normal and default behaviour is to let the RTEMS Source +Builder install the tools. The source will be downloaded, built, installed and +cleaned up. + +The tar files are created with the full build prefix present and if you follow +the examples given in this documentation the path is absolute. This can cause +problems if you are installing on a host you do not have super user or +administrator rights on because the prefix path may references part you do not +have write access too and tar will not extract the files. You can use the +``--strip-components`` option in tar if your host tar application supports it +to remove the parts you do not have write access too or you may need to unpack +the tar file somewhere and copy the file tree from the level you have write +access from. Embedding the full prefix path in the tar files lets you know what +the prefix is and is recommended. For example if +``/home/chris/development/rtems/4.11`` is the prefix used you cannot change +directory to the root (``/``) and untar the file because the ``/home`` is root +access only. To install a tar file you have downloaded into your new machine's +``Downloads`` directory in your home directoty you would enter: + +.. code-block:: shell + + $ cd /somewhere + $ tar --strip-components=3 -xjf \ + $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2 + +A build set tar file is created by adding ``--bset-tar-file`` option to the +``sb-set-builder`` command:: + + $ ../source-builder/sb-set-builder --log=l-sparc.txt \ + --prefix=$HOME/development/rtems/4.11 \ + --bset-tar-file \ <1> + 4.11/rtems-sparc + Source Builder - Set Builder, v0.2.0 + Build Set: 4.11/rtems-sparc + config: expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-freebsd9.1-1 + building: expat-2.1.0-x86_64-freebsd9.1-1 + config: tools/rtems-binutils-2.22-1.cfg + package: sparc-rtems4.11-binutils-2.22-1 + building: sparc-rtems4.11-binutils-2.22-1 + config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg + package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + config: tools/rtems-gdb-7.5.1-1.cfg + package: sparc-rtems4.11-gdb-7.5.1-1 + building: sparc-rtems4.11-gdb-7.5.1-1 + installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2> + installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 + installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 + installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 + tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> + cleaning: expat-2.1.0-x86_64-freebsd9.1-1 + cleaning: sparc-rtems4.11-binutils-2.22-1 + cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + cleaning: sparc-rtems4.11-gdb-7.5.1-1 + Build Set: Time 0:15:25.92873 + +.. topic:: Items + + 1. The option to create a build set tar file. + + 2. The installation still happens unless you specify ``--no-install``. + + 3. Creating the build set tar file. + +You can also suppress installing the files using the ``--no-install`` +option. This is useful if your prefix is not accessiable, for example when +building Canadian cross compiled tool sets:: + + $ ../source-builder/sb-set-builder --log=l-sparc.txt \ + --prefix=$HOME/development/rtems/4.11 \ + --bset-tar-file \ + --no-install \ <1> + 4.11/rtems-sparc + Source Builder - Set Builder, v0.2.0 + Build Set: 4.11/rtems-sparc + config: expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-freebsd9.1-1 + building: expat-2.1.0-x86_64-freebsd9.1-1 + config: tools/rtems-binutils-2.22-1.cfg + package: sparc-rtems4.11-binutils-2.22-1 + building: sparc-rtems4.11-binutils-2.22-1 + config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg + package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + config: tools/rtems-gdb-7.5.1-1.cfg + package: sparc-rtems4.11-gdb-7.5.1-1 + building: sparc-rtems4.11-gdb-7.5.1-1 + tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2> + cleaning: expat-2.1.0-x86_64-freebsd9.1-1 + cleaning: sparc-rtems4.11-binutils-2.22-1 + cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + cleaning: sparc-rtems4.11-gdb-7.5.1-1 + Build Set: Time 0:14:11.721274 + $ ls tar + rtems-4.11-sparc-rtems4.11-1.tar.bz2 + +.. topic:: Items + + 1. The option to supressing installing the packages. + + 2. Create the build set tar. + +A package tar file can be created by adding the ``--pkg-tar-files`` to the +``sb-set-builder`` command. This creates a tar file per package built in the +build set:: + + $ ../source-builder/sb-set-builder --log=l-sparc.txt \ + --prefix=$HOME/development/rtems/4.11 \ + --bset-tar-file \ + --pkg-tar-files \ <1> + --no-install 4.11/rtems-sparc + Source Builder - Set Builder, v0.2.0 + Build Set: 4.11/rtems-sparc + config: expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-freebsd9.1-1 + building: expat-2.1.0-x86_64-freebsd9.1-1 + config: tools/rtems-binutils-2.22-1.cfg + package: sparc-rtems4.11-binutils-2.22-1 + building: sparc-rtems4.11-binutils-2.22-1 + config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg + package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + config: tools/rtems-gdb-7.5.1-1.cfg + package: sparc-rtems4.11-gdb-7.5.1-1 + building: sparc-rtems4.11-gdb-7.5.1-1 + tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 + cleaning: expat-2.1.0-x86_64-freebsd9.1-1 + cleaning: sparc-rtems4.11-binutils-2.22-1 + cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 + cleaning: sparc-rtems4.11-gdb-7.5.1-1 + Build Set: Time 0:14:37.658460 + $ ls tar + expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2 + sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> + sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2 + +.. topic:: Items + + 1. The option to create packages tar files. + + 2. The GDB package tar file. + + 3. The build set tar file. All the others in a single tar file. + Support ======= .. index:: Support -- cgit v1.2.3