From 166fded4c91ee4f29495f3b8531969db14ed76f9 Mon Sep 17 00:00:00 2001 From: Juergen Borleis Date: Thu, 7 Dec 2017 10:22:41 +0100 Subject: Doc: avoid syntax highlighting by accident Some tools try to be smart and thus using an improper syntax highlighting. This change avoids guessing the highlighting by explicitly define it. Signed-off-by: Juergen Borleis --- doc/dev_manual.rst | 74 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 36 deletions(-) (limited to 'doc') diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst index 6a66f0745..cf5726429 100644 --- a/doc/dev_manual.rst +++ b/doc/dev_manual.rst @@ -241,7 +241,7 @@ Rule File Creation To create such a new package, we create a project local ``rules/`` directory first. Then we run -:: +.. code-block:: text $ ptxdist newpackage @@ -251,14 +251,14 @@ package types. In our first example, we want to add a new target type archive package. When running the -:: +.. code-block:: text $ ptxdist newpackage target command, PTXdist asks a few questions about this package. This information is the basic data PTXdist must know about the package. -:: +.. code-block:: text ptxdist: creating a new 'target' package: @@ -374,7 +374,7 @@ After enabling the menu entry, we can start to check the *get* and archives between PTXdist based projects. Advantage is every download happens only once. Refer to the ``setup`` command PTXdist provides. -:: +.. code-block:: text $ ptxdist get foo @@ -398,7 +398,7 @@ in use is correct. the rule file. To get an idea what content a variable has, we can ask PTXdist about it: -:: +.. code-block:: text $ ptxdist print FOO_URL http://www.foo.com/download/src/foo-1.1.0.tar.gz @@ -407,7 +407,7 @@ The next step would be to extract the archive. But as PTXdist checks the MD5 sum in this case, this step will fail, because the ``FOO_MD5`` variable is still empty. Let’s fill it: -:: +.. code-block:: text $ md5sum /global_src/foo-1.1.0.tar.gz 9a09840ab775a139ebb00f57a587b447 @@ -415,13 +415,13 @@ variable is still empty. Let’s fill it: This string must be assigned to the FOO\_MD5 in our new ``foo.make`` rule file: -:: +.. code-block:: text FOO_MD5 := 9a09840ab775a139ebb00f57a587b447 We are now prepared for the next step: -:: +.. code-block:: text $ ptxdist extract foo @@ -442,7 +442,7 @@ prepare the build, the archive comes with a ``configure`` script. This is the default case for PTXdist. So, there is no need to modify the rule file and we can simply run: -:: +.. code-block:: text $ ptxdist prepare foo @@ -494,7 +494,7 @@ first. If the *prepare* stage has finished successfully, the next step is to compile the package. -:: +.. code-block:: text $ ptxdist compile foo @@ -536,7 +536,7 @@ features to simplify this task. In this example we expect the best case: everything went fine, even for cross compiling. So, we can continue with the next stage: *install* -:: +.. code-block:: text $ ptxdist install foo @@ -606,13 +606,13 @@ From the previous *install* stage we know this package installs an executable called ``foo`` to location ``/usr/bin``. We can do the same for our target by changing the *install\_copy* line to: -:: +.. code-block:: make @$(call install_copy, foo, 0, 0, 0755, $(FOO_DIR)/foo, /usr/bin/foo) To check it, we just run: -:: +.. code-block:: text $ ptxdist targetinstall foo @@ -662,7 +662,7 @@ our new entry to. We just have to edit the head of our new menu file package is a network related tool, the head of the menu file should look like: -:: +.. code-block:: kconfig ## SECTION=networking @@ -670,7 +670,7 @@ We can grep through the other menu files from the PTXdist main installation ``rules/`` directory to get an idea what section names are available: -:: +.. code-block:: text rules/ $ find . -name \*.in | xargs grep "## SECTION" ./acpid.in:## SECTION=shell_and_console @@ -690,7 +690,7 @@ Porting a new package to PTXdist is (almost) finished now. To check it right away, we simply run these two commands: -:: +.. code-block:: text $ ptxdist clean foo rm -rf /home/jbe/my_new_prj/state/foo.* @@ -710,7 +710,7 @@ results are working on the target. So to check for this kind of dependencies there is still one more final check to do (even if its boring and takes time): -:: +.. code-block:: text $ ptxdist clean [...] @@ -754,7 +754,7 @@ be given to ``configure``. Currently this variable is commented out and defined to: -:: +.. code-block:: make # FOO_CONF_OPT := $(CROSS_AUTOCONF_USR) @@ -765,7 +765,7 @@ contains all basic parameters to instruct ``configure`` to prepare for a To use the two additional mentioned ``configure`` parameters, we comment in this line and supplement this expression as follows: -:: +.. code-block:: make FOO_CONF_OPT := $(CROSS_AUTOCONF_USR) \ --enable-debug \ @@ -777,7 +777,7 @@ in this line and supplement this expression as follows: To do a fast check if this addition was successful, we run: -:: +.. code-block:: text $ ptxdist print FOO_CONF_OPT --prefix=/usr --sysconfdir=/etc --host=|ptxdistCompilerName| --build=i686-host-linux-gnu --enable-debug --with-bar @@ -788,7 +788,7 @@ To do a fast check if this addition was successful, we run: Or re-build the package with the new settings: -:: +.. code-block:: text $ ptxdist drop foo prepare $ ptxdist targetinstall foo @@ -877,7 +877,7 @@ To support this process, PTXdist supplies a helper script, located at ``/path/to/ptxdist/scripts/configure-helper.py`` that compares the configure output with the settings from ``FOO_CONF_OPT``: -:: +.. code-block:: text $ /opt/ptxdist-2017.06.0/scripts/configure-helper.py -p libsigrok --- rules/libsigrok.make @@ -939,7 +939,7 @@ modify our *targetinstall* stage: Now we can play with our new menu entries and check if they are working as expected: -:: +.. code-block:: text $ ptxdist menuconfig $ ptxdist targetinstall foo @@ -955,7 +955,7 @@ missing external dependency. For example: -:: +.. code-block:: text checking whether zlib exists....failed @@ -1237,7 +1237,7 @@ Using quilt We create a special directory for the patch series in the local project directory: -:: +.. code-block:: text $ mkdir -p patches/foo-1.1.0 @@ -1246,7 +1246,7 @@ one patch. Otherwise it fails. Due to the fact that we do not have any patch content yet, we’ll start with a dummy entry in the ``series`` file and an empty ``patch`` file. -:: +.. code-block:: text $ touch patches/foo-1.1.0/dummy $ echo dummy > patches/foo-1.1.0/series @@ -1254,7 +1254,7 @@ and an empty ``patch`` file. Next is to extract the package (if already done, we must remove it first): -:: +.. code-block:: text $ ptxdist extract foo @@ -1277,14 +1277,16 @@ Using Git """"""""" Create the patch directory like above for *quilt*, -but only add an empty series file:: +but only add an empty series file + +.. code-block:: text $ mkdir -p patches/foo-1.1.0 $ touch patches/foo-1.1.0/series Then extract the package with an additional command line switch: -:: +.. code-block:: text $ ptxdist --git extract foo @@ -1304,7 +1306,7 @@ patch the required source files, and make Git commits on the way. The Git history should now look something like this: -:: +.. code-block:: text $ git log --oneline --decorate * df343e821851 (HEAD -> master) Makefile: don't build the tests @@ -1368,7 +1370,7 @@ package was patched (while the *extract* stage is running). Its content depends on developer needs; for the most simple case the content can be: -:: +.. code-block:: bash #!/bin/bash @@ -1410,7 +1412,7 @@ Add binary Files File by File Doing to on a file by file base can happen by just using the ``install_copy`` macro in the *targetinstall* stage in our own customized rules file. -:: +.. code-block:: make @$(call install_copy, binary_example, 0, 0, 0644, \ ptx_logo.png, \ @@ -1440,7 +1442,7 @@ correct manner: - user and group ID on a per file base -:: +.. code-block:: make @$(call install_archive, binary_example, -, -, \ archive.tgz, /) @@ -1464,7 +1466,7 @@ Creating a Rules File Let PTXdist create one for us. -:: +.. code-block:: text $ ptxdist newpackage file @@ -1485,7 +1487,7 @@ Both files now must be customized to meet our requirements. Due to the answer *rootfs* to the “``enter package section``” question, we will find the new menu entry in: -:: +.. code-block:: text Root Filesystem ---> < > my_binfiles (NEW) @@ -1493,7 +1495,7 @@ find the new menu entry in: Enabling this new entry will also run our stages in ``rules/my_binfiles.make`` the next time we enter: -:: +.. code-block:: text $ ptxdist go -- cgit v1.2.3