diff options
-rw-r--r-- | doc/dev_manual.rst | 2 | ||||
-rw-r--r-- | doc/environment.rst | 66 | ||||
-rw-r--r-- | doc/ref_manual.rst | 4 | ||||
-rw-r--r-- | doc/user_manual.rst | 48 |
4 files changed, 60 insertions, 60 deletions
diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst index dfd2c040b..e89857549 100644 --- a/doc/dev_manual.rst +++ b/doc/dev_manual.rst @@ -67,7 +67,7 @@ package in question. One location is the project’s currently used platform directory. If the currently used platform is located in ``configs/``, PTXdist searches in -./configs/\ |ptxdistPlatformName|\ /patches/<package name> +./configs/|ptxdistPlatformName|/patches/<package name> If no patch series was found in the platform directory, the next location PTXdist it searches for a patch series is the main project diff --git a/doc/environment.rst b/doc/environment.rst index f840c9581..3362832ba 100644 --- a/doc/environment.rst +++ b/doc/environment.rst @@ -17,10 +17,10 @@ components which are available to the public). In order to build |ptxdistBSPName|, the following source archives have to be available on the development host: - * ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2 - * |ptxdistBSPName|\ .tar.bz2 - * ptxdist-\ |oselasTCNVendorptxdistversion|\ .tar.bz2 - * OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ .tar.bz2 + * ptxdist-|ptxdistVendorVersion|.tar.bz2 + * |ptxdistBSPName|.tar.bz2 + * ptxdist-|oselasTCNVendorptxdistversion|.tar.bz2 + * OSELAS.Toolchain-|oselasTCNVendorVersion|.tar.bz2 Main Parts of PTXdist ~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +82,7 @@ else. To install PTXdist, the archive Pengutronix provides has to be extracted: -ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2 +ptxdist-|ptxdistVendorVersion|.tar.bz2 The PTXdist software itself The PTXdist archive has to be extracted into some temporary directory in @@ -98,16 +98,16 @@ to create it and change into it: Next step is to extract the archive: -.. parsed-literal:: +:: - $ tar -xjf ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2 + $ tar -xjf ptxdist-|ptxdistVendorVersion|.tar.bz2 -If everything goes well, we now have a PTXdist-\ |ptxdistVendorVersion| directory, so we can +If everything goes well, we now have a PTXdist-|ptxdistVendorVersion| directory, so we can change into it: -.. parsed-literal:: +:: - $ cd ptxdist-\ |ptxdistVendorVersion| + $ cd ptxdist-|ptxdistVendorVersion| $ ls -lF total 530 -rw-r--r-- 1 jb user 18446 Sep 9 15:59 COPYING @@ -149,7 +149,7 @@ to be done now is to configure the packet: This will check your system for required components PTXdist relies on. If all required components are found the output ends with: -.. parsed-literal:: +:: [...] checking whether Python development files are present... yes @@ -446,18 +446,18 @@ Install the binary OSELAS Toolchain Now everything is in place to install the binary OSELAS toolchain for the board support package: -.. parsed-literal:: +:: - $ apt-get install oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -<ptxdistCompilerVersion> + $ apt-get install oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-<ptxdistCompilerVersion> These package names are very long and hard to type without making typos. An easier way is to ask the package manager for available toolchains and just use the name by copy and paste it. -.. parsed-literal:: +:: - $ apt-cache search "oselas.toolchain-.*-\ |oselasTCNarch|\ .*\ |oselasTCNvariant|\ .*" - oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -<ptxdistCompilerVersion> + $ apt-cache search "oselas.toolchain-.*-|oselasTCNarch|.*|oselasTCNvariant|.*" + oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-<ptxdistCompilerVersion> The binary OSELAS Toolchain Package for non-Debian Distributions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -469,11 +469,11 @@ The related OSELAS toolchain package can be found here: Subpath is: -| oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -\ |ptxdistCompilerVersion|\ / +| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|/ Package filename is: -| oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -\ |ptxdistCompilerVersion|\ \*.deb +| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|\*.deb Package filenames for 32 bit host machines are ending on ``*_i386.deb`` and for 64 bit host machines on ``*_amd64.deb``. @@ -485,8 +485,8 @@ PTXdist handles toolchain building as a simple project, like all other projects, too. So we can download the OSELAS.Toolchain bundle and build the required toolchain for the OSELAS.BoardSupport() Package. -Building any toolchain of the OSELAS.Toolchain-\ |oselasTCNVendorVersion| is -tested with PTXdist-\ |oselasTCNVendorptxdistversion|. +Building any toolchain of the OSELAS.Toolchain-|oselasTCNVendorVersion| is +tested with PTXdist-|oselasTCNVendorptxdistversion|. Pengutronix recommends to use this specific PTXdist to build the toolchain. So, it might be essential to install more than one PTXdist revision to build the toolchain and later on the Board Support Package @@ -497,7 +497,7 @@ directory; all OSELAS.Toolchain projects that come with PTXdist are configured to use the standard installation paths mentioned below. All OSELAS.Toolchain projects install their result into -/opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /. +/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/. Usually the ``/opt`` directory is not world writeable. So in order to build our OSELAS.Toolchain into that directory we need to use a root @@ -505,11 +505,11 @@ account to change the permissions. PTXdist detects this case and asks if we want to run ``sudo`` to do the job for us. Alternatively we can enter: -.. parsed-literal:: +:: - $ mkdir /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion| - $ chown <username> /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion| - $ chmod a+rwx /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion| + $ mkdir /opt/OSELAS.Toolchain-|oselasTCNVendorVersion| + $ chown <username> /opt/OSELAS.Toolchain-|oselasTCNVendorVersion| + $ chmod a+rwx /opt/OSELAS.Toolchain-|oselasTCNVendorVersion| We recommend to keep this installation path as PTXdist expects the toolchains at ``/opt``. Whenever we go to select a platform in a @@ -534,7 +534,7 @@ compiler in question and start the build. The required compiler to build the board support package is -|oselasToolchainName|\ .ptxconfig +|oselasToolchainName|.ptxconfig .. important:: In order to build any of the OSELAS.Toolchains, the host must provide the tool *fakeroot*. Otherwise the @@ -549,12 +549,12 @@ The required compiler to build the board support package is So the steps to build this toolchain are: -.. parsed-literal:: +:: - $ tar xf OSELAS.Toolchain-\ |oselasTCNVendorVersion|.tar.bz2 - $ cd OSELAS.Toolchain-\ |oselasTCNVendorVersion| - $ ptxdist-\ |oselasTCNVendorptxdistversion| select ptxconfigs/\ |oselasToolchainName|\ .ptxconfig - $ ptxdist-\ |oselasTCNVendorptxdistversion| go + $ tar xf OSELAS.Toolchain-|oselasTCNVendorVersion|.tar.bz2 + $ cd OSELAS.Toolchain-|oselasTCNVendorVersion| + $ ptxdist-|oselasTCNVendorptxdistversion| select ptxconfigs/|oselasToolchainName|.ptxconfig + $ ptxdist-|oselasTCNVendorptxdistversion| go At this stage we have to go to our boss and tell him that it’s probably time to go home for the day. Even on reasonably fast machines the time @@ -607,10 +607,10 @@ new one. All toolchains will be installed side by side architecture dependent into directory -| /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|/<architecture> +| /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/<architecture> Different toolchains for the same architecture will be installed side by side version dependent into directory -| /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|/<architecture>/<version> +| /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/<architecture>/<version> diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst index da2a3ff86..4201c945f 100644 --- a/doc/ref_manual.rst +++ b/doc/ref_manual.rst @@ -12,10 +12,10 @@ are changed. To get their content related to the current project, we can simply run a: -.. parsed-literal:: +:: $ ptxdist print PTXDIST_TOPDIR - /usr/local/lib/ptxdist-\ |release| + /usr/local/lib/ptxdist-|release| Replace the ``PTXDIST_TOPDIR`` with one of the other generic variables PTXdist provides. diff --git a/doc/user_manual.rst b/doc/user_manual.rst index f011edcd0..fe4ae1745 100644 --- a/doc/user_manual.rst +++ b/doc/user_manual.rst @@ -255,9 +255,9 @@ Extracting the Board Support Package In order to work with a PTXdist based project we have to extract the archive first. -.. parsed-literal:: +:: - $ tar -zxf |ptxdistBSPName|\ .tar.gz + $ tar -zxf |ptxdistBSPName|.tar.gz $ cd |ptxdistBSPName| PTXdist is project centric, so now after changing into the new directory @@ -332,21 +332,21 @@ Selecting a Hardware Platform Before we can build this BSP, we need to select one of the possible platforms to build for. In this case we want to build for the : -.. parsed-literal:: +:: - $ ptxdist platform configs/\ |ptxdistPlatformName|\ /platformconfig\ |ptxdistPlatformVariant| + $ ptxdist platform configs/|ptxdistPlatformName|/platformconfig|ptxdistPlatformVariant| info: selected platformconfig: - 'configs/\ |ptxdistPlatformName|\ /platformconfig\ |ptxdistPlatformVariant|\ ' + 'configs/|ptxdistPlatformName|/platformconfig|ptxdistPlatformVariant|' .. note:: If you have installed the OSELAS.Toolchain() at its default location, PTXdist should already have detected the proper toolchain while selecting the platform. In this case it will output: -.. parsed-literal:: +:: found and using toolchain: - '/opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /\ |ptxdistCompilerName|\ /\ - |ptxdistCompilerVersion|\ /bin' + '/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/|ptxdistCompilerName|/\ + |ptxdistCompilerVersion|/bin' If it fails you can continue to select the toolchain manually as mentioned in the next section. If this autodetection was successful, we @@ -361,11 +361,11 @@ specific cases. To reduce the package count for the run: -.. parsed-literal:: +:: - $ ptxdist collection configs/\ |ptxdistPlatformCollection| + $ ptxdist collection configs/|ptxdistPlatformCollection| info: selected collectionconfig: - 'configs/\ |ptxdistPlatformCollection|\ ' + 'configs/|ptxdistPlatformCollection|' Selecting a Toolchain ~~~~~~~~~~~~~~~~~~~~~ @@ -374,9 +374,9 @@ If not automatically detected, the last step in selecting various configurations is to select the toolchain to be used to build everything for the target. -.. parsed-literal:: +:: - $ ptxdist toolchain /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /\ |ptxdistCompilerName|\ /\ |ptxdistCompilerVersion|\ /bin + $ ptxdist toolchain /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/|ptxdistCompilerName|/|ptxdistCompilerVersion|/bin Building the Root Filesystem Content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -496,9 +496,9 @@ working QEMU on our development host. Simply run -.. parsed-literal:: +:: - $ ./configs/\ |ptxdistPlatformName|\ /run + $ ./configs/|ptxdistPlatformName|/run This will start QEMU in full system emulation mode and runs the previously built kernel which then uses the generated disk image to @@ -673,10 +673,10 @@ To do so, we run: In this Kconfig dialogue we navigate to the entry: -.. parsed-literal:: +:: Linux kernel ---> - (\ |ptxdistPlatformKernelRev|\ ) kernel version + (|ptxdistPlatformKernelRev|) kernel version and replace the 3.19 value by the 4.0 value. @@ -688,11 +688,11 @@ Now we can leave the menu and save the new settings. A Linux kernel needs a configuration for being built correctly. The project comes with a prepared configuration in the file -configs/\ |ptxdistPlatformName|\ /kernelconfig-3.0 for the 3.0 kernel. +configs/|ptxdistPlatformName|/kernelconfig-3.0 for the 3.0 kernel. It is always a good idea to start with a known-to-work kernel configuration. So, for this example, we are using a different -known-to-work kernel configuration in the configs/\ |ptxdistPlatformName|\ /kernelconfig-3.7 +known-to-work kernel configuration in the configs/|ptxdistPlatformName|/kernelconfig-3.7 file for our new 3.7 kernel. Adapting Linux Kernel Settings @@ -736,10 +736,10 @@ When PTXdist has finished its job, the new bootable kernel can be found at ``images/linuximage``. To boot it again in the QEMU emulation, the hard disk image must be re-created with: -.. parsed-literal:: +:: $ ptxdist images - $ ./configs/\ |ptxdistPlatformName|\ /run + $ ./configs/|ptxdistPlatformName|/run The emulated system should now start with a 3.7 based kernel with USB support. @@ -759,9 +759,9 @@ such packages. In this simple example, we want to add the missing ``head`` command to our target’s shell. Assuming we forgot to enable this command, we get: -.. parsed-literal:: +:: - $ ./configs/\ |ptxdistPlatformName|\ /run + $ ./configs/|ptxdistPlatformName|/run ptx login: root login[xxx]: root login on 'ttyS0' @@ -799,7 +799,7 @@ change. And also once again, after finishing its job, the following commands let us test the new command: -.. parsed-literal:: +:: $ ptxdist images $ ./configs/|ptxdistPlatformName|/run |