Fixing build script in Linux to look for depthengine.so* inside a sub…

…folder. Fixing docs to reflect these changes.
microsoft · jaygullapalli · Mar 24, 2021 · Dec 9, 2020 · Dec 9, 2020 · Dec 9, 2020
commit bd1cad97c442f8e9aa93bea27af244b554fc8614
diff --git a/src/python/k4a/build_wheel.csh b/src/python/k4a/build_wheel.csh
@@ -26,8 +26,8 @@ if [ ! -f "$DIR/src/k4a/_libs/libk4a.so" ] && [ ! -h "$DIR/src/k4a/_libs/libk4a.
     return 1
 fi
 
-if [ ! -f "$DIR/src/k4a/_libs/libdepthengine*" ] && [ ! -h "$DIR/src/k4a/_libs/libdepthengine*" ]; then
-    echo "File not found: $DIR/src/k4a/_libs/libdepthengine*"
+if [ ! -f "$DIR/src/k4a/_libs/libk4a"*"/libdepthengine"* ] && [ ! -h "$DIR/src/k4a/_libs/libk4a"*"/libdepthengine"* ]; then
+    echo "File not found: $DIR/src/k4a/_libs/libk4a*/libdepthengine*"
     echo "Please manually copy the depth engine library into that folder."
     return 1
 fi
@@ -77,4 +77,4 @@ echo '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://ww
 deactivate
 rm -rf "temp_build_venv"
 
-echo "Done creating k4a package wheel."
+echo "Done creating k4a package wheel."
diff --git a/src/python/k4a/docs/building.md b/src/python/k4a/docs/building.md
@@ -52,7 +52,7 @@ separately:
 The following tools are optional:
 
 * [doxygen](https://github.com/doxygen/doxygen)
-  Required for building documentation.
+  Required for building documentation. If not installed, html documentation will not be built.
 
 
 ## Building
@@ -65,17 +65,29 @@ The following tools are optional:
     >**Note:** To create a cross-platform wheel, the .dll for Windows and the .so for Linux need to
     >copied into the folder. Python will look for "k4a.dll" in Windows and "libk4a.so" in Linux.
 
+    >**Note:** An example of the files in _libs for Windows are: 
+    >- k4a.dll
+    >- depthengine\_2\_0.dll
+
 2. In a powershell terminal, run the script src/python/k4a/build_wheel.ps1.
    This will create the .whl file in a build/ folder.
 
 ### Building using a bash script (Linux)
 
 1. Copy the k4a and DE binaries into the folder src/python/k4a/src/k4a/_libs.
-   The file name for the k4a library MUST be libk4a.so.
+   The file name for the k4a library MUST be libk4a.so. The depth engine library must be in a
+   folder named libk4a\<ver\>, where \<ver\> is the version major.minor of the k4a library
+   (e.g. _libs constains libk4a1.4/libdepthengine.so.2.0).
 
     >**Note:** To create a cross-platform wheel, the .dll for Windows and the .so for Linux need to
     >copied into the folder. Python will look for "k4a.dll" in Windows and "libk4a.so" in Linux.
 
+    >**Note:** An example of the files in _libs for Linux are: 
+    >- libk4a.so, a soft link to libk4a.1.4
+    >- libk4a.so.1.4, a soft link to libk4a.1.4.0
+    >- libk4a.so.1.4.1, the k4a library
+    >- libk4a1.4/depthengine.so.2.0, the depth engine library in a sub-folder
+
 2. In a terminal, source the script src/python/k4a/build_wheel.csh.
    This will create the .whl file in a build/ folder.
 
@@ -90,6 +102,14 @@ The following tools are optional:
     >**Note:** To create a cross-platform wheel, the .dll for Windows and the .so for Linux need to
     >copied into the folder. Python will look for "k4a.dll" in Windows and "libk4a.so" in Linux.
 
+    >**Note:** An example of the files in _libs for cross-platform compatibility are: 
+    >- libk4a.so, a soft link to libk4a.1.4
+    >- libk4a.so.1.4, a soft link to libk4a.1.4.0
+    >- libk4a.so.1.4.1, the k4a library
+    >- libk4a1.4/depthengine.so.2.0, the depth engine library in a sub-folder
+    >- k4a.dll
+    >- depthengine\_2\_0.dll
+
 2. In a command line terminal, create a Python virtual environment and activate it (do not include brackets):
     `cd <repo_root>/src/python/k4a`  
     `python -m venv <env_name>`  
@@ -119,4 +139,4 @@ The wheel file can be distributed and installed as follows.
    Replace <k4a*.whl> with the name of the wheel file.
     `pip install <k4a*.whl>`
 
-Once installed, the user can "import k4a" in their python code.
+Once installed, the user can "import k4a" in their python code.
diff --git a/src/python/k4a/docs/testing.md b/src/python/k4a/docs/testing.md
@@ -19,12 +19,19 @@ The following are required in order to run the Python K4A tests.
 
 ## Running tests
 
+>**Note:** The commands `python` and `pip` in Windows are assumed to be `python3` and `pip3`.
+> In Linux, they are not aliased to Python3, so `python3` and `pip3` may have to be used in
+> the instructions below.
+
 ### Setting up the test environment
 
 1. Copy the k4a and DE dynamic libraries (.dll or .so) into the folder src/python/k4a/src/k4a/_libs. 
-   The file names for the k4a library MUST be k4a.dll (for Windows) and libk4a.so (for Linux).
+   The file names for the k4a library MUST be k4a.dll (for Windows) and libk4a.so (for Linux).  
+
+   >**Note:** Read [building.md](./building.md) for more information on how to copy the libraries into
+   >the _libs folder. The file names and folder structure are slightly different in Windows and Linux.  
 
-2. In a command line terminal, create a Python virtual environment and activate it (do not include brackets):
+2. In a command line terminal, create a Python virtual environment and activate it (do not include brackets):  
     `cd <repo_root>/src/python/k4a`  
     `python -m venv <env_name>`  
 
@@ -111,4 +118,4 @@ very long time. Consider running these tests one by one. Additionally, the tests
 capture live data and may fail if the data cannot be transformed from one camera
 to another. For example, this may happen if the selected pixel to transform is an
 invalid pixel in the depth image just because the data at that pixel is not in the
-range of depths that the depth sensor can see.
+range of depths that the depth sensor can see.