Skip to content
This repository was archived by the owner on Mar 26, 2026. It is now read-only.

Commit ac340db

Browse files
DefinetlyNotAIDefinetlyNotAI
committed
Update README.md to enhance clarity on build methods and directory structure
1 parent 6f91194 commit ac340db

1 file changed

Lines changed: 76 additions & 44 deletions

File tree

‎README.md‎

Lines changed: 76 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -10,67 +10,98 @@ This project provides a cross-language toolkit for Windows process inspection an
1010
> [!IMPORTANT]
1111
> To get the `dist` binary folder, choose **one** of the following options:
1212
>
13-
> | Method | Description | Requirements |
14-
> |-----------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
15-
> | Manual Build | Compile the binaries yourself using `cl.exe` or similar toolchains | Microsoft Visual Studio with MSVC installed |
16-
> | Auto Build Script | Run the [`tool/compilerHelper.ps1`](https://github.com/DefinetlyNotAI/PyCTools/blob/main/tool/compilerHelper.ps1) PowerShell script | Visual Studio Build Tools + PowerShell |
17-
> | Prebuilt Release Archive | Download precompiled binaries from the [releases page](https://github.com/DefinetlyNotAI/PyCTools/releases/tag/v1.0.0) | None (just extract archive) |
13+
> | Method | Description | Requirements |
14+
> |--------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
15+
> | Manual Build | Compile the binaries yourself using `cl.exe` or similar toolchains | Microsoft Visual Studio with MSVC installed |
16+
> | Auto Build Script | Run the [`tool/compilerHelper.ps1`](tool/compilerHelper.ps1) PowerShell script | Visual Studio Build Tools + PowerShell |
17+
> | Prebuilt Release Archive | Download precompiled binaries from the [releases page](https://github.com/DefinetlyNotAI/PyCTools/releases/) | None, make sure to use the latest available version |
1818
>
19-
> No matter what you decide, do still read the important notice about the `dist` from the [release](https://github.com/DefinetlyNotAI/PyCTools/releases/tag/v1.0.0) OR check the [Wiki](https://github.com/DefinetlyNotAI/PyCTools/wiki/DLL-Discovery) page about the DLL discovery explanation.
19+
> No matter what you decide, do still read the important notice about the `dist` from the [release](https://github.com/DefinetlyNotAI/PyCTools/releases/) OR check the [Wiki](https://github.com/DefinetlyNotAI/PyCTools/wiki#dll-discovery-and-dist-directory) page about the DLL discovery explanation.
2020
2121
## Directory Structure
2222

2323
<details>
2424
<summary>📁 Project Structure (click to expand)</summary>
2525

26-
example/
27-
pyCTools/
28-
hwrng.py # Python wrapper for hardware RNG DLL
29-
processInspect.py # Python wrapper for process inspection DLL
30-
hwrng_example.py # Example: hardware RNG usage
31-
process_inspect_example.py # Example: process metrics usage
32-
src/
33-
hRng.c # C source for hardware RNG DLL
34-
processInspect.c # C source for process inspection DLL
35-
tool/
36-
compilerHelper.ps1 # PowerShell script to build DLLs for x86/x64
37-
dist/
38-
x64/ # Compiled DLLs for 64-bit
39-
x86/ # Compiled DLLs for 32-bit
26+
root/
27+
├── bin/ # Auto-generated folder containing compiled DLL binaries
28+
│ ├── x86/ # 32-bit DLL builds
29+
│ └── x64/ # 64-bit DLL builds
30+
│
31+
├── dist/ # Release artifacts for distribution
32+
│ ├── bin.zip # Zipped prebuilt binaries
33+
│ └── bin.zip.sha256 # SHA256 checksum for `bin.zip`
34+
│
35+
├── examples/ # Example Python scripts demonstrating usage
36+
│ ├── hwrng_example.py # Example: Hardware RNG usage
37+
│ ├── process_inspect_example.py # Example: Process inspection usage
38+
│ └── rng_tests/ # RNG test scripts and outputs
39+
│ ├── rng_output.bin # 10M bytes of RNG data (complexity 1, threaded)
40+
│ ├── rng_entropy_output.png # PNG entropy visualization of RNG output
41+
│ ├── Results.txt # Test results from `rng_test.py`
42+
│ ├── rng_test.py # Script to test hardware RNG
43+
│ └── generate_bin.py # Generates binary file from RNG
44+
│
45+
├── pyCTools/ # Python package (library code)
46+
│ ├── __init__.py # Package initializer
47+
│ ├── hwrng.py # Hardware RNG DLL wrapper
48+
│ ├── processInspect.py # Process inspection DLL wrapper
49+
│ └── _loadDLL.py # DLL loading logic used by wrappers
50+
│
51+
├── tool/ # Build and distribution tools
52+
│ ├── compilerHelper.ps1 # Compiles C code into DLLs
53+
│ └── distributionHelper.ps1 # Creates `bin.zip` and SHA256 checksum
54+
│
55+
├── src/ # C source code for DLLs
56+
│ ├── hRng.c # Hardware RNG implementation
57+
│ └── processInspect.c # Process inspection implementation
58+
│
59+
└── CMakeLists.txt # CMake build configuration (currently unused)
4060

4161
</details>
4262

4363
## Building the DLLs
4464

45-
1. Open PowerShell and run `tool/compilerHelper.ps1`.
46-
2. Select which `.c` files to compile.
47-
3. The script will build both x86 and x64 DLLs and place them in `dist/x86` and `dist/x64`.
65+
1. Open **PowerShell** and run:
66+
```powershell
67+
cd ./tool/
68+
compilerHelper.ps1
69+
```
70+
71+
2. Choose the `.c` source files you want to compile.
4872

49-
## Using the Python Library
73+
3. The script will compile for **both x86 and x64** architectures, placing the output in:
74+
- `bin/x86` (32-bit builds)
75+
- `bin/x64` (64-bit builds)
5076

51-
- Place the `dist/` folder as a sibling to your Python scripts or as described in the wrappers.
52-
- Import and use `pyCTools.hwrng` or `pyCTools.processInspect` as shown in the examples.
77+
> [!IMPORTANT]
78+
> The build process uses `cl.exe` from the **MSVC toolchain** in Visual Studio, so make sure it’s installed and available in your PATH.
79+
80+
> [!NOTE]
81+
> - Each compiled source produces **four files per architecture**: `.dll`, `.exp`, `.lib`, and `.obj`.
82+
>
83+
> - Only the `.dll` is needed by the Python library.
84+
>
85+
> - DLL filenames include an architecture suffix:
86+
>
87+
> - Example: `hRng_x86.dll`, `hRng_x64.dll`.
5388
54-
## Example Usage
89+
## Using the Python Library
5590

56-
**Hardware RNG:**
57-
```python
58-
from pyCTools.hwrng import get_hardware_random_bytes
59-
rb = get_hardware_random_bytes(16)
60-
print(rb.hex())
61-
```
91+
- Place the `dist/` folder inside the `pyCTools` package directory, or at max two levels up the library.
92+
- Import and use `hwrng` or `processInspect` from `pyCTools`.
93+
- The library will automatically load the correct DLL based on your Python interpreter architecture (x86 or x64).
6294

63-
**Process Inspection:**
64-
```python
65-
from pyCTools.processInspect import ProcessMetrics
66-
metrics = ProcessMetrics()
67-
pid = 1234 # Target PID
68-
flags = ProcessMetrics.METRIC_WORKING_SET | ProcessMetrics.METRIC_CPU_USAGE
69-
snapshot = metrics.get_snapshot(pid, flags)
70-
print(snapshot)
71-
```
95+
> [!TIP]
96+
> Example usages for both modules in detail:
97+
>
98+
> #### Hardware RNG
99+
> Either check out the [example script](example/hwrng_example.py) or the [Wiki page](https://github.com/DefinetlyNotAI/PyCTools/wiki/Py-Documentation-‐-hwrng#methods)
100+
>
101+
> #### Process Inspection
102+
> Either check out the [example script](example/process_inspect_example.py) or the [Wiki page](https://github.com/DefinetlyNotAI/PyCTools/wiki/Py-Documentation-‐-processInspect#methods)
72103
73-
## DLL Discovery
104+
### DLL Discovery
74105

75106
The Python wrappers automatically search for the correct DLL in:
76107
- `./dist/{arch}/<dll>`
@@ -79,6 +110,8 @@ The Python wrappers automatically search for the correct DLL in:
79110

80111
where `{arch}` is `x64` or `x86` depending on your Python interpreter.
81112

113+
> More details on how the DLL discovery works can be found in the [Wiki page](https://github.com/DefinetlyNotAI/PyCTools/wiki#dll-discovery-and-dist-directory)
114+
82115
## Extra resources
83116

84117
> [!TIP]
@@ -87,4 +120,3 @@ where `{arch}` is `x64` or `x86` depending on your Python interpreter.
87120
> • **DLL explanations**: learn how the DLLs are structured, discovered, and loaded
88121
> • **Python examples, wrappers, and usage**: practical code snippets and usage patterns in Python
89122
> • **C code explanation**: understand the underlying native implementation
90-

0 commit comments

Comments
 (0)