Skip to content

Commit bbe2872

Browse files
abdollahShahidabdollahShahid
committed
docs: complete d2d options reference page
Signed-off-by: Muhammad Abdullah Shahid <108458621+abdollahShahid@users.noreply.github.com>
1 parent fa58819 commit bbe2872

1 file changed

Lines changed: 85 additions & 5 deletions

File tree

‎docs/d2d-options.rst‎

Lines changed: 85 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,91 @@ Reference Documentation Page: d2d options and capabilities
33

44
This page lists the available d2d options and highlights the capabilities present for each optional ecosystem option.
55

6+
Overview
7+
--------
8+
9+
d2d (deploy-to-devel) workflows are used to map deployed artifacts (such as compiled binaries and archives)
10+
back to their most likely source code.
11+
12+
The current d2d helper script runs the ``map_deploy_to_develop`` mapping workflow in ScanCode.io inside a
13+
Docker container. It can optionally spin up a temporary PostgreSQL database when needed.
14+
15+
Usage
16+
-----
17+
18+
.. code-block:: bash
19+
20+
./map-deploy-to-develop.sh <from-path> <to-path> <output-file> [options] <spin-db> [db-port]
21+
22+
Arguments
23+
---------
24+
25+
+-----------------+-------------------------------------------------------------+
26+
| Argument | Description |
27+
+=================+=============================================================+
28+
| ``from-path`` | Path to the base deployment/scan file |
29+
+-----------------+-------------------------------------------------------------+
30+
| ``to-path`` | Path to the target deployment/scan file |
31+
+-----------------+-------------------------------------------------------------+
32+
| ``options`` | D2D pipeline parameters (can be empty ``""``) |
33+
+-----------------+-------------------------------------------------------------+
34+
| ``output-file`` | File where ScanCode.io output will be written |
35+
+-----------------+-------------------------------------------------------------+
36+
| ``spin-db`` | ``true`` = spin temp DB container, ``false`` = skip |
37+
+-----------------+-------------------------------------------------------------+
38+
| ``db-port`` | Port to bind Postgres (default: ``5432``) |
39+
+-----------------+-------------------------------------------------------------+
40+
641
Capabilities matrix
742
-------------------
843

9-
+------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
10-
| d2d option | compiled file -> source file | archive -> source directory | binary/source symbols | archives -> purlDB | source files -> purlDB |
11-
+==================+==============================+==============================+===========================+=======================+==========================+
12-
| TODO | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ |
13-
+------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
44+
The helper script executes the ``map_deploy_to_develop`` mapping workflow. The exact capabilities depend on the
45+
D2D pipeline parameters passed through the ``options`` argument.
46+
47+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
48+
| d2d option / parameter | compiled file -> source file | archive -> source directory | binary/source symbols | archives -> purlDB | source files -> purlDB |
49+
+==========================================+==============================+==============================+===========================+=======================+==========================+
50+
| Base mapping workflow (default) | ✅ | ✅ | depends on parameters | depends on parameters | depends on parameters |
51+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
52+
| ``options`` (pipeline parameters) | ✅ | ✅ | ✅/❌ | ✅/❌ | ✅/❌ |
53+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
54+
| ``spin-db=true`` (temporary DB enabled) | ✅ | ✅ | depends on parameters | depends on parameters | depends on parameters |
55+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
56+
| ``spin-db=false`` (no DB container) | ✅ | ✅ | depends on parameters | depends on parameters | depends on parameters |
57+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
58+
| ``db-port=<port>`` | ✅ | ✅ | depends on parameters | depends on parameters | depends on parameters |
59+
+------------------------------------------+------------------------------+------------------------------+---------------------------+-----------------------+--------------------------+
60+
61+
Examples
62+
--------
63+
64+
Run mapping without database:
65+
66+
.. code-block:: bash
67+
68+
./map-deploy-to-develop.sh ./from.tar.gz ./to.whl results.json "" false
69+
70+
Run mapping with database on a custom port:
71+
72+
.. code-block:: bash
73+
74+
./map-deploy-to-develop.sh ./from.tar.gz ./to.whl output.json "Python,Java" true 5433
75+
76+
Script actions (high-level)
77+
---------------------------
78+
79+
1. Validates required arguments
80+
2. Starts PostgreSQL in Docker (if ``spin-db=true``)
81+
3. Creates a temporary working directory: ``./d2d``
82+
4. Copies input files into working directory
83+
5. Runs ScanCode.io mapping step
84+
6. Writes mapping output into ``output-file``
85+
7. Cleans up temp directory
86+
8. Stops DB container if it was started
87+
88+
Related files
89+
-------------
90+
91+
- Script: ``etc/scripts/d2d/map-deploy-to-develop.sh``
92+
- README: ``etc/scripts/d2d/README.rst``
93+
- Reference docs index: :doc:`index`

0 commit comments

Comments
 (0)