FIX documentation

telefonicaid · Sep 6, 2023 · 16fced2 · 16fced2
1 parent c3c827d
commit 16fced2
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 49 deletions.
diff --git a/doc/manuals.jp/admin/build_source.md b/doc/manuals.jp/admin/build_source.md
@@ -1,16 +1,16 @@
 # ソースからのビルド
 
-Orion Context Broker のリファレンス配布は Debian 11 です。これは、broker を他のディストリビューションに組み込むことができないことを意味しません (実際には可能です)。このセクションでは、他のディストリビューションをビルドする方法についても説明しています。Debian を使用していない人に役立つかもしれません。ただし、"公式にサポートされている" 唯一の手順は Debian 11 用の手順です。他のものは "現状のまま" 提供され、随時時代遅れになる可能性があります。
+Orion Context Broker のリファレンス配布は Debian 12 です。これは、broker を他のディストリビューションに組み込むことができないことを意味しません (実際には可能です)。このセクションでは、他のディストリビューションをビルドする方法についても説明しています。Debian を使用していない人に役立つかもしれません。ただし、"公式にサポートされている" 唯一の手順は Debian 12 用の手順です。他のものは "現状のまま" 提供され、随時時代遅れになる可能性があります。
 
 ## Debian 11 (正式サポート)
 
 Orion Context Broker は、以下のライブラリをビルドの依存関係として使用します :
 
 * boost: 1.74
 * libmicrohttpd: 0.9.76 (ソースから)
-* libcurl: 7.74.0
-* openssl: 1.1.1n
-* libuuid: 2.36.1
+* libcurl: 7.88.1
+* openssl: 3.0.9
+* libuuid: 2.38.1
 * libmosquitto: 2.0.15 (ソースから)
 * Mongo C driver: 1.24.3 (ソースから)
 * rapidjson: 1.1.0 (ソースから)
@@ -94,12 +94,12 @@ Orion Context Broker には、次の手順に従って実行できる一連の
 
 * ソースから GoogleTest/Mock をインストールします。以前の URL は http://googlemock.googlecode.com/files/gmock-1.5.0.tar.bz2 でしたが、Google は2016年8月下旬にそのパッケージを削除し、機能しなくなりました。
 
-        sudo apt-get install python2
         wget https://nexus.lab.fiware.org/repository/raw/public/storage/gmock-1.5.0.tar.bz2
         tar xfvj gmock-1.5.0.tar.bz2
         cd gmock-1.5.0
         ./configure
-        sed -i 's/env python/env python2/' gtest/scripts/fuse_gtest_files.py  # little hack to make installation to work on Debian 11
+        # Adjust /path/to/fiware-orion in the next line accordingly to where you local copy of fiware-orion repo is in your system
+        patch -p1 gtest/scripts/fuse_gtest_files.py < /path/to/fiware-orion/test/unittests/fuse_gtest_files.py.patch
         make
         sudo make install  # installation puts .h files in /usr/local/include and library in /usr/local/lib
         sudo ldconfig      # just in case... it doesn't hurt :)
@@ -123,9 +123,9 @@ aarch64 アーキテクチャの場合、apt-get を使用して libxslt をイ
         export PATH=~/bin:$PATH
         make install_scripts INSTALL_DIR=~
         . scripts/testEnv.sh
-        virtualenv /opt/ft_env --python=/usr/bin/python3
+        python3 -m venv /opt/ft_env   # or 'virtualenv /opt/ft_env --python=/usr/bin/python3' in some systems
         . /opt/ft_env/bin/activate
-        pip install Flask==2.0.2 paho-mqtt==1.6.1 amqtt==0.10.1
+        pip install Flask==2.0.2 paho-mqtt==1.6.1 amqtt==0.11.0b1
 
 * この環境でテスト・ハーネスを実行してください (時間がかかりますので、気をつけてください)
 

diff --git a/doc/manuals.jp/admin/install.md b/doc/manuals.jp/admin/install.md
@@ -26,8 +26,8 @@ Docker hub で公式の Orion docker コンテナを使用してインストー
 
 必要なソースから ビルドした Orion をインストールする場合：
 
-* オペレーティングシステム: Debian。リファレンス・オペレーティングシステムは Debian 11.6 ですが、それ以降の
-  Debian 11 バージョンでも動作するはずです
+* オペレーティングシステム: Debian。リファレンス・オペレーティングシステムは Debian 12.1 ですが、それ以降の
+  Debian 12 バージョンでも動作するはずです
 * データベース: MongoDB は、Orion Context Broker がインストールされるのと同じホストで実行するか、ネットワーク経由で
   アクセスできる別のホストで実行する必要があります。推奨される MongoDB バージョンは 4.4 です (Orion は古いバージョンで
   動作する可能性がありますが、まったくお勧めしません!)

diff --git a/doc/manuals/admin/build_source.md b/doc/manuals/admin/build_source.md
@@ -1,16 +1,16 @@
 # Building from sources
 
-Orion Context Broker reference distribution is Debian 11. This doesn't mean that the broker cannot be built in other distributions (actually, it can). This section also includes indications on how to build in other distributions, just in the case it may help people that don't use Debian. However, note that the only "officially supported" procedure is the one for Debian 11; the others are provided "as is" and can get obsolete from time to time.
+Orion Context Broker reference distribution is Debian 12. This doesn't mean that the broker cannot be built in other distributions (actually, it can). This section also includes indications on how to build in other distributions, just in the case it may help people that don't use Debian. However, note that the only "officially supported" procedure is the one for Debian 12; the others are provided "as is" and can get obsolete from time to time.
 
-## Debian 11 (officially supported)
+## Debian 12 (officially supported)
 
 The Orion Context Broker uses the following libraries as build dependencies:
 
 * boost: 1.74
 * libmicrohttpd: 0.9.76 (from source)
-* libcurl: 7.74.0
-* openssl: 1.1.1n
-* libuuid: 2.36.1
+* libcurl: 7.88.1
+* openssl: 3.0.9
+* libuuid: 2.38.1
 * libmosquitto: 2.0.15 (from source)
 * Mongo C driver: 1.24.3 (from source)
 * rapidjson: 1.1.0 (from source)
@@ -93,38 +93,43 @@ The Orion Context Broker comes with a suite of unit, valgrind and end-to-end tes
 
 * Install Google Test/Mock from sources. Previously the URL was http://googlemock.googlecode.com/files/gmock-1.5.0.tar.bz2 but Google removed that package in late August 2016 and it is no longer working.
 
-        sudo apt-get install python2
         wget https://nexus.lab.fiware.org/repository/raw/public/storage/gmock-1.5.0.tar.bz2
         tar xfvj gmock-1.5.0.tar.bz2
         cd gmock-1.5.0
         ./configure
-        sed -i 's/env python/env python2/' gtest/scripts/fuse_gtest_files.py  # little hack to make installation to work on Debian 11
+        # Adjust /path/to/fiware-orion in the next line accordingly to where you local copy of fiware-orion repo is in your system
+        patch -p1 gtest/scripts/fuse_gtest_files.py < /path/to/fiware-orion/ci/deb/fuse_gtest_files.py.patch
         make
         sudo make install  # installation puts .h files in /usr/local/include and library in /usr/local/lib
         sudo ldconfig      # just in case... it doesn't hurt :)
 
 In the case of the aarch64 architecture, install libxslt using apt-get, and run `./configure` with `--build=arm-linux` option.
 
-* Install MongoDB (tests rely on mongod running in localhost). Check [the official MongoDB documentation](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-red-hat/) for details. Recommended version is 4.4 (it may work with previous versions, but we don't recommend it).
+* Install MongoDB (tests rely on mongod running in localhost). Check [the official MongoDB documentation](hhttps://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-debian/) for details. Recommended version is 4.4 (it may work with previous versions, but we don't recommend it).
+    * Note that mongo legacy shell (the `mongo` command) has been deprecated in MongoDB 5 and removed in MongoDB 6 in favour of the new shell (`mongosh` command). Some functional tests (ftest) will fail due to this if you use MongoDB 6 or beyond, as they are suited to use `mongo` and not `mongosh`.
+    * Debian 12 has stepped to libssl3 but some MongoDB versions may require libssl1. In the case you get a `Depends: libssl1.1 (>= 1.1.1) but it is not installable` error, you can test the following (reference [here](https://askubuntu.com/a/1421959))
+
+        wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+        sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+        rm libssl1.1_1.1.1f-1ubuntu2_amd64.deb     # optional, for cleanness
 
 * Run unit test
 
         make unit_test
 
 * Install additional required tools for functional and valgrind tests:
 
-        sudo apt-get install curl nc valgrind bc python3 python3-pip
-        sudo pip3 install virtualenv
+        sudo apt-get install curl netcat-traditional valgrind bc python3 python3-pip mosquitto
 
 * Prepare the environment for test harness. Basically, you have to install the `accumulator-server.py` script and in a path under your control, `~/bin` is the recommended one. Alternatively, you can install them in a system directory such as `/usr/bin` but it could collide with an other programs, thus it is not recommended. In addition, you have to set several environment variables used by the harness script (see `scripts/testEnv.sh` file) and create a virtualenv environment with the required Python packages.
 
         mkdir ~/bin
         export PATH=~/bin:$PATH
         make install_scripts INSTALL_DIR=~
         . scripts/testEnv.sh
-        virtualenv /opt/ft_env --python=/usr/bin/python3
+        python3 -m venv /opt/ft_env   # or 'virtualenv /opt/ft_env --python=/usr/bin/python3' in some systems
         . /opt/ft_env/bin/activate
-        pip install Flask==2.0.2 paho-mqtt==1.6.1 amqtt==0.10.1
+        pip install Flask==2.0.2 paho-mqtt==1.6.1 amqtt==0.11.0b1
 
 * Run test harness in this environment (it takes some time, please be patient).
 
@@ -138,7 +143,7 @@ You can generate coverage reports for the Orion Context Broker using the followi
 
 * Install the lcov tool
 
-        sudo apt-get install lcov
+        sudo apt-get install lcov xsltproc
 
 * Do first a successful pass for unit_test and functional_test, to check that everything is ok (see above)
 

diff --git a/doc/manuals/admin/install.md b/doc/manuals/admin/install.md
@@ -23,8 +23,8 @@ In the case you install using the official Orion docker container at Dockerhub,
 
 In the case you are installing Orion building from sources you need:
 
-* Operating system: Debian. The reference operating system is Debian 11.6
-  but it should work also in any later Debian 11 version.
+* Operating system: Debian. The reference operating system is Debian 12.1
+  but it should work also in any later Debian 12 version.
 * Database: MongoDB is required to run either in the same host where Orion Context Broker is to be installed or in a different host accessible through the network. The recommended MongoDB version
   is 4.4 (Orion may work with older versions but we don't recommend it at all!).
 

diff --git a/doc/manuals/devel/cookbook.md b/doc/manuals/devel/cookbook.md
@@ -187,19 +187,17 @@ A functional test file contains six sections:
 2. NAME section
 3. SHELL-INIT section
 4. SHELL section
-5. EXPECT/REGEXPECT section
+5. REGEXPECT section
 6. TEARDOWN section
 
 Each section (except the Copyright preamble, that starts at the beginning of the file) must have a header, that tells the functional test harness where every section starts/ends:
 
 * `--NAME--`
 * `--SHELL-INIT--`
 * `--SHELL--`
-* `--REGEXPECT--` / `--EXPECT--`
+* `--REGEXPECT--`
 * `--TEARDOWN--`
 
-If `--REGEXPECT--` is used (and not `--EXPECT--`), then the expected section permits regular expressions. That is the only different between these two.
-
 ### Copyright section
 This section is simply for the Copyright header. Copy an old one. Try to remember to change the year, if necessary.
 
@@ -275,7 +273,7 @@ echo "0x. description of test step 0x"
 echo "==============================="  
 ```
 
-and the steps end with two calls to `echo`, to separate the current step from the next in the output. This is pretty important as it makes it **so much** easier to read the output, which must match what is in the section that follows, the **EXPECT/REGEXPECT** section.
+and the steps end with two calls to `echo`, to separate the current step from the next in the output. This is pretty important as it makes it **so much** easier to read the output, which must match what is in the section that follows, the **REGEXPECT** section.
 
 A typical step (e.g. to create an entity) looks like this:  
 
@@ -300,22 +298,16 @@ echo
 echo
 ```
 
-### EXPECT/REGEXPECT Section
+### REGEXPECT Section
 First of all, the test harness (`test/functionalTest/testHarness.sh`) admits two types of 'expect sections'. Either
 
 ```
---EXPECT--
-```
-
-or
-
-```
---REG-EXPECT--
+--REGEXPECT--
 ```
 
-You have to **pick one**. Pretty much **all** current functests use the `--REG-EXPECT--` type. The advantage with --REG-EXPECT-- is that it permits to add regular expressions using the `REGEX()` syntax, which is very important for the comparison of dates, or IDs created by Orion and returned in the response, like a registration id or a correlator or a simple timestamp. An important limitation is that there can only be **one REGEX** per line in the REG-EXPECT section.
+It permits to add regular expressions using the `REGEX()` syntax, which is very important for the comparison of dates, or IDs created by Orion and returned in the response, like a registration id or a correlator or a simple timestamp. An important limitation is that there can only be **one REGEX** per line in the REGEXPECT section.
 
-That said, in the REG-EXPECT section, just add what is the expected output from the test step in question. For example, the example "01. Create entity E1 with attribute A1" from the above sub-chapter about the SHELL section would
+That said, just add what is the expected output from the test step in question. For example, the example "01. Create entity E1 with attribute A1" from the above sub-chapter about the SHELL section would
 have this corresponding piece in the --REGEXPECT-- section:  
 
 ```
@@ -339,6 +331,8 @@ Note the two occurrences of `REGEX()`, for the correlator and the date:
 where each hyphen must come, however, it's not really necesary.  
 * The second REGEX, for the `Date` HTTP header could also be more elaborated. Also not necessary.
 
+You can include comments in the REGEXPECT section. Any line starting with `##` in the `--REGEXPECT--` section is ignored.
+
 ### TEARDOWN Section
 This is where processes are killed and databases are removed, so that the following test case will start with a clean slate. The most typical commands used are:
 

diff --git a/test/functionalTest/README.jp.md b/test/functionalTest/README.jp.md
@@ -28,7 +28,7 @@ virtualenv --python=/usr/bin/python3 /path/to/ft_env
 ```
 pip install Flask==2.0.2
 pip install paho-mqtt==1.6.1
-pip install amqtt==0.10.1  # Not actually an accumulator-server.py dependency, but needed by some tests
+pip install amqtt==0.11.0b1  # Not actually an accumulator-server.py dependency, but needed by some tests
 ```
 
 次に、accumulator-server.py のスクリプト自体をインストールします:

diff --git a/test/functionalTest/README.md b/test/functionalTest/README.md
@@ -26,7 +26,7 @@ Next install accumulator-server.py depencencies:
 ```
 pip install Flask==2.0.2
 pip install paho-mqtt==1.6.1
-pip install amqtt==0.10.1  # Not actually an accumulator-server.py dependency, but needed by some tests
+pip install amqtt==0.11.0b1  # Not actually an accumulator-server.py dependency, but needed by some tests
 ```
 
 Next, install the accumulator-server.py script itself:

diff --git a/test/functionalTest/cases/README.md b/test/functionalTest/cases/README.md
@@ -1,7 +1 @@
-This directory contains several subdirectories. Each subdirectory starts with a number, which identifies the issue number at GitHub associated with the .test contained in that subdirectory (except the ones starting with `0000`, which are not associated with any GitHub issue).
-
-Subdirectories can be classified in 3 groups:
-
-* The ones with "ngsi10" substring in the name, corresponding to NGSI10 functionality.
-* The ones with "ngsi9" substring in the name, corresponding to  NGSI9 functionality.
-* The ones without "ngsi10" or "ngsi9" in the name, corresponding to functionalities not directly related to NGSI9 or NGSI10, because they are orthogonal (i.e. applicable to both) or are not related to NGSI (e.g. CLI tests).
+This directory contains several subdirectories. Each subdirectory starts with a number, which identifies the issue number at GitHub associated with the .test contained in that subdirectory (except the ones starting with `0000`, which are not associated with any GitHub issue).