Skip to content

Commit f754bb7

Browse files
Nivedhidha-INivedhidha-I
committed
readme file qbout installation
1 parent 1a0b7c1 commit f754bb7

File tree

1 file changed

+99
-93
lines changed

1 file changed

+99
-93
lines changed

‎readme.md

Lines changed: 99 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,60 @@
11

2-
# **Installing BCC (BPF Compiler Collection) on Ubuntu 24.04 with Python Virtual Environment** For JAMJAR
2+
# **JamJar Installation Guide (Ubuntu 24.04 + Python Virtual Environment)**
33

4+
This guide covers installing the [BPF Compiler Collection (BCC)](https://github.com/iovisor/bcc/blob/master/INSTALL.md) from source on **Ubuntu 24.04** inside a **Python virtual environment**, including troubleshooting common installation issues.
45

56

6-
This guide provides steps to install [BCC](https://github.com/iovisor/bcc/blob/master/INSTALL.md) from source on **Ubuntu 24.04** using a **Python virtual environment** instead of system-wide installation.
7-
87
---
98

109
## **🔧 Prerequisites**
1110

12-
You need Ubuntu version - 24.04
11+
Make sure your system is Ubuntu 24.04 or similar.
1312

14-
Before starting, make sure you have the following installed:
13+
Update and install system packages:
1514

1615
```
17-
sudo apt update
18-
sudo apt upgrade
16+
sudo apt update && sudo apt upgrade -y
1917
sudo apt install -y unzip zip bison build-essential cmake flex git libedit-dev \
20-
libllvm18 llvm-18-dev libclang-18-dev python3 zlib1g-dev libelf-dev libfl-dev python3-setuptools \
21-
liblzma-dev libdebuginfod-dev arping netperf iperf libpolly-18-dev
18+
libllvm18 llvm-18-dev libclang-18-dev python3 zlib1g-dev libelf-dev libfl-dev python3-setuptools \
19+
liblzma-dev libdebuginfod-dev arping netperf iperf libpolly-18-dev libcurl4-openssl-dev libluajit-5.1-dev
20+
2221
```
2322

24-
These packages are internally used by bcc's dependencies and will be installed in ubuntu by default and will create issues when you are building bcc.
23+
These packages are needed for building BCC and its dependencies.
2524

2625
```
27-
sudo apt install libcurl4-openssl-dev libluajit-5.1-dev
28-
```
26+
2927
---
3028
31-
## **📦 Installation Steps**
32-
### **1. Clone JamJar from Github
29+
## **🧹 Cleanup (Start fresh)**
3330
34-
```
35-
git clone https://www.github.com/hashedalgorithm/JamJar.git
36-
```
31+
If you've attempted installation before and want to start clean, remove these folders and files:
32+
33+
rm -rf ~/JamJar/bcc
34+
rm -rf ~/JamJar/python-ptrace-0.9.9
35+
rm -rf ~/JamJar/0.9.9.zip
36+
rm -rf ~/JamJar/jamjar-venv
3737
3838
---
3939
40-
### **2. Create a Python Virtual Environment**
40+
## **📦 Installation Steps**
41+
### **1. Clone JamJar Repository from Github
4142
4243
```
43-
python3 -m venv ~/JamJar/jamjar-venv
44+
git clone https://github.com/hashedalgorithm/JamJar.git
45+
cd JamJar
4446
```
47+
---
4548
46-
This ensures that Python bindings for BCC are installed in an isolated environment.
47-
48-
Activate the virtual environment (if not already):
49+
### **2. Create and activate Python virtual environment**
4950
5051
```
51-
source ~/JamJar/jamjar-venv/bin/activate
52+
python3 -m venv jamjar-venv
53+
source jamjar-venv/bin/activate
5254
```
5355
56+
This ensures that Python bindings for BCC are installed in an isolated environment.
57+
5458
---
5559
5660
### **3. Clone the BCC Repository**
@@ -62,7 +66,7 @@ cd bcc
6266
6367
---
6468
65-
### **4. Change Folder Ownership (Recommended for Virtualized/Root-Owned Folders)**
69+
### **4. Fix folder ownership (if cloned with sudo or running in VM)**
6670
6771
If you’re using a virtual machine or ran git clone with sudo, you may need to change the folder’s ownership:
6872
@@ -81,129 +85,128 @@ cd build
8185
8286
---
8387
84-
### **6. Install Python Dependencies (for your venv)**
88+
### **6. Install Python Dependencies (inside venv)**
8589
8690
```
8791
pip install six setuptools ipcalc build
8892
```
8993
90-
> ⚠️ If you are getting errors then the reason for it would be ownership issues with the folder.
94+
> ⚠️ If permission or dependency errors arise, check folder ownership and your virtual environment activation.
9195
9296
---
9397
9498
### **7. Build and Install BCC Core**
9599
96100
```
97101
cmake ..
98-
make $(nproc)
99-
make install
102+
make -j$(nproc)
103+
sudo make install
100104
```
101105
106+
> **Note:** sudo is needed here because installing to /usr/lib requires root permissions.
107+
102108
---
103109
104-
### **8. Installing ptrace(0.9.9 stable) from source**
110+
### **8. Build and Install Python Bindings (for your venv)**
111+
112+
From within the build directory:
105113
106114
```
107-
// Go to ~/JamJar
108-
wget https://github.com/vstinner/python-ptrace/archive/refs/tags/0.9.9.zip
109-
unzip 0.9.9.zip
110-
cd python-ptrace-0.9.9/
115+
cd ../bcc
116+
cmake -DPYTHON_CMD=python3 .
117+
cd src/python
118+
make -j$(nproc)
119+
python3 setup.py install
111120
```
112121
113-
```
114-
python3 -m build
115-
```
116-
This creates a .whl file in the dist/ directory.
122+
> ⚠️ **Important:** Do NOT run sudo make install here; the Python bindings must install in the virtual environment.
123+
124+
---
125+
126+
## **✅ Verifying Installation**
127+
128+
Activate your virtual environment and run:
117129
118130
```
119-
pip install dist/*.whl
131+
python3 -c "from bcc import BPF; print('✅ BCC Python bindings installed!')"
132+
120133
```
121134
135+
If this prints without errors, BCC is ready to use.
136+
137+
> 🤩 Tip : Check the make logs and verify that everything is installed correctly
138+
122139
---
123140
124-
### **9. Build and Install Python Bindings (for your venv)**
141+
## **🚩 Common Issues and Solutions**
142+
### **1. ModuleNotFoundError: No module named 'bcc.version'**
125143
126-
From within the build directory:
144+
Cause: version.py file missing in bcc/ directory.
145+
146+
Fix: Create a version.py in bcc/ with the following content:
127147
128148
```
129-
cd ../bcc
130-
cmake -DPYTHON_CMD=python3 ./
131-
pushd ./src/python
132-
make $(nproc)
133-
python3 ./bcc-python3/setup.py install
134-
popd
149+
__version__ = "0.35.0"
135150
```
136151
137-
> ⚠️ **Do not use sudo make install here**, since you’re installing in a virtual environment.
152+
Confirm your current directory is the root of BCC Python source (bcc/src/python/) when running Python commands.
138153
139154
---
140155
141-
## **✅ Verifying Installation**
156+
### **2. Permission Denied on make install for BCC core libraries**
142157
143-
Try running a sample Python program using BCC:
158+
Cause: You need root permission to install shared libraries into /usr/lib.
144159
145-
```
146-
ubuntu@VM:~$ python3
147-
Python 3.12.3 (main, Feb 4 2025, 14:48:35) [GCC 13.3.0] on linux
148-
Type "help", "copyright", "credits" or "license" for more information.
149-
>>> from bcc import BPF
150-
>>> import ptrace
151-
>>>
160+
Fix: Use sudo make install during core BCC installation.
161+
162+
---
163+
164+
### **3. Errors during pip install or building Python bindings**
165+
166+
Cause: Folder ownership issues or missing dependencies.
167+
168+
Fix: Ensure the entire BCC repo directory is owned by your user:
152169
170+
```
171+
sudo chown -R $(whoami):$(whoami) ~/JamJar/bcc
153172
```
154173
155-
If this prints without errors, BCC is ready to use. If throws error in either of these you just to make, build and install again.
174+
Make sure your Python virtual environment is activated before installing.
156175
157-
> 🤩 Tip : Check the make logs and verify that everything is installed correctly
158176
---
159177
160-
## **🧹 Cleanup (Optional)**
178+
### **4. Bash error: bash: !': event not found when running python -c with exclamation marks**
161179
162-
If you no longer need the source or build artifacts:
180+
Cause: Bash interprets ! as history expansion.
181+
182+
Fix: Use single quotes instead of double quotes or escape !:
163183
164184
```
165-
sudo rm -rf ~/JamJar-main/bcc
166-
sudo rm -rf ~/JamJar-main/python-ptrace-0.9.9
167-
sudo rm -r ~/JamJar-main/0.9.9.zip
185+
python3 -c 'from bcc import BPF; print("✅ BCC installed!")'
168186
```
169187
170-
---
171-
172-
<<<<<<< HEAD
173-
## **🍯 Running JamJar **
188+
Make sure your Python virtual environment is activated before installing.
174189
175-
JamJar needs su permissions to work hence it handles with kernal operations. even if you try to run it sudo it doesn't work. Hence we need root shell. To obtain root shell in ubuntu
190+
---
176191
177-
### **👤 Change Password of Root User
178-
=======
179192
## **🍯 Running JamJar**
180193
181-
JamJar needs su permissions to work hence it handles with kernal operations. even if you try to run it sudo it doesn't work. Hence we need root shell. To obtain root shell in ubuntu
182-
183-
### **👤 Change Password of Root User**
184-
>>>>>>> v2-ls
194+
JamJar requires root privileges due to kernel operations.
185195
196+
1. Set root password:
186197
```
187-
ubuntu@VM:~$ sudo passwd root
188-
[sudo] password for ubuntu:
189-
New password:
190-
Retype new password:
191-
passwd: password updated successfully
198+
sudo passwd root
199+
192200
```
193201
194-
<<<<<<< HEAD
195-
### **🦾 Get Root Shell
196-
=======
197-
### **🦾 Get Root Shell**
198-
>>>>>>> v2-ls
202+
> ⚠️ If you came across any error like module not found try to install it using pip(except for bcc and ptrace).
199203
204+
2. Switch to root shell:
200205
```
201-
ubuntu@VM:~$ su
202-
Password:
203-
root@VM:/home/ubuntu#
206+
su
204207
```
205208
206-
Now navigate to JamJar and activate your venv and run main.py
209+
3. Navigate to JamJar, activate venv and run:
207210
```
208211
cd ~/JamJar
209212
source jamjar-venv/bin/activate
@@ -212,9 +215,12 @@ python3 main.py
212215
213216
> ⚠️ If you came across any error like module not found try to install it using pip(except for bcc and ptrace).
214217
215-
216-
<<<<<<< HEAD
217218
---
218-
=======
219-
---
220-
>>>>>>> v2-ls
219+
220+
## **🧹 Cleanup (Optional)**
221+
222+
If you no longer need the source or build artifacts:
223+
224+
```
225+
sudo rm -rf ~/JamJar/bcc
226+
```

0 commit comments

Comments
 (0)