Skip to content

Commit 33f3275

Browse files
rahlkrahlk
committed
Update frontpage and add detailed installation instructions.
Signed-off-by: Rahul Krishna <i.m.ralk@gmail.com>
1 parent 03de8b9 commit 33f3275

11 files changed

Lines changed: 1124 additions & 769 deletions

File tree

‎docs/assets/css/theme.css‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -58,11 +58,11 @@ figcaption {
5858
overflow-y: hidden;
5959
}
6060

61-
/* Apply Kolena branding colors on top of 'default' scheme */
61+
/* Apply IBM branding colors on top of 'default' scheme */
6262
[data-md-color-scheme="default"] {
6363
--md-primary-fg-color: #0F62FE;
6464
--md-primary-fg-color--dark: #452485;
65-
--md-primary-fg-color--light: #835dcd;
65+
--md-primary-fg-color--light: #d4e3ff;
6666

6767
--md-typeset-a-color: #0F62FE; /* manually set link color to indigo */
6868

@@ -74,18 +74,17 @@ figcaption {
7474
--md-mg-insertion-color: #3e57d3;
7575
}
7676

77-
/* Apply Kolena branding on top of 'slate' (dark) scheme */
77+
/* Apply IBM branding on top of 'slate' (dark) scheme */
7878
@media screen {
7979
[data-md-color-scheme="slate"] {
8080
--md-primary-fg-color: #0F62FE;
8181
--md-primary-fg-color--dark: #332362;
8282
--md-primary-fg-color--light: #835dcd;
8383

84-
--md-typeset-a-color: #5F72FF; /* manually set link color to indigo */
84+
--md-typeset-a-color: #5f72ff; /* manually set link color to indigo */
8585

8686
--md-hue: 216;
8787

88-
/* crank down the saturation of these default colors -- less purplish than simply overriding --md-hue */
8988
--md-default-fg-color: hsla(var(--md-hue), 25%, 95%, 1);
9089
--md-default-fg-color--light: hsla(var(--md-hue), 25%, 90%, 0.62);
9190
--md-default-fg-color--lighter: hsla(var(--md-hue), 25%, 90%, 0.32);
@@ -115,7 +114,33 @@ figcaption {
115114
/* custom admonition type for FAQ */
116115
:root {
117116
--md-admonition-icon--faq: url('data:image/svg+xml;charset=utf-8,<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 16 16" enable-background="new 0 0 16 16" xml:space="preserve"><g id="flag_1_"><path fill-rule="evenodd" clip-rule="evenodd" d="M2.99,2.99c-0.55,0-1,0.45-1,1v11c0,0.55,0.45,1,1,1s1-0.45,1-1v-11C3.99,3.44,3.54,2.99,2.99,2.99z M2.99-0.01c-0.55,0-1,0.45-1,1s0.45,1,1,1s1-0.45,1-1S3.54-0.01,2.99-0.01z M4.99,3.02v7.23c2.07-2.11,5.92,1.75,9,0V3.02C10.99,5.09,7.05,0.99,4.99,3.02z"/></g></svg>');
117+
--md-tip-border-color: #0F62FE;
118+
--md-tip-bg-color: #0F62FE;
119+
--md-tip-text-color: #edf3ff;
118120
}
121+
122+
[data-md-color-scheme="dark"] {
123+
--md-tip-text-color: var(--md-default-fg-color--lighter);
124+
}
125+
126+
.md-typeset .admonition.tip,
127+
.md-typeset details.tip {
128+
border-color: var(--md-tip-border-color);
129+
}
130+
131+
.md-typeset .tip > .admonition-title,
132+
.md-typeset .tip > summary {
133+
background-color: var(--md-tip-bg-color);
134+
color: var(--md-tip-text-color);
135+
}
136+
137+
.md-typeset .tip > .admonition-title::before,
138+
.md-typeset .tip > summary::before {
139+
background-color: #edf3ff;
140+
-webkit-mask-image: var(--md-admonition-icon--tip);
141+
mask-image: var(--md-admonition-icon--tip);
142+
}
143+
119144
.md-typeset .admonition.faq,
120145
.md-typeset details.faq {
121146
border-color: var(--md-typeset-table-color);

‎docs/index.md‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ CLDK streamlines the process of transforming raw code into actionable insights,
3737

3838
# :cldk-layers-20: Developer Guide
3939

40-
Learn how to use Codellm-devkit to analyze your code effectively:
40+
Get started with Codellm-devkit:
4141

4242
<div class="grid cards" markdown>
4343

@@ -68,6 +68,50 @@ Learn how to use Codellm-devkit to analyze your code effectively:
6868
</div>
6969
---
7070

71+
---
72+
73+
# :cldk-learning-20: Use Cases
74+
75+
Learn how to leverage CLDK for various code analysis tasks:
76+
77+
<div class="grid cards" markdown>
78+
79+
- [:cldk-test-suite-16: Java Unit Test Generation](usecases/java/unit_test.md)
80+
81+
---
82+
83+
Understand how to use CLDK to generate unit tests for Java projects.
84+
85+
- [:cldk-text-summarization-16: Summarize Python Projects](usecases/python/explain.md)
86+
87+
---
88+
89+
Learn how to summarize Python projects using CLDK.
90+
91+
</div>
92+
---
93+
94+
# :cldk-rocket-20: Advanced Topics
95+
96+
Dive deeper into advanced topics
97+
98+
<div class="grid cards" markdown>
99+
100+
- [:cldk-rocket-16: Extending CLDK](advanced/extending.md)
101+
102+
---
103+
104+
Learn how to extend CLDK to a new language.
105+
106+
- [:cldk-workflow-16: Adding a New Analysis Backend](advanced/adding_backend.md)
107+
108+
---
109+
110+
Learn how to add a new analysis backend to CLDK.
111+
112+
</div>
113+
---
114+
71115
## Why Codellm-devkit?
72116

73117
!!! tip inline "TL;DR"

‎docs/installing.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
icon: cldk/developer-20
3+
---
4+
5+
# :cldk-developer-20: Installing `cldk`
6+
7+
[`CLDK`](https://github.com/IBM/codellm-devkit) is a Python SDK [hosted on PyPI](https://pypi.org/project/cldk/) and can be installed using your preferred Python package manager.
8+
9+
## Installation
10+
11+
The Python SDK can be installed directly from
12+
[PyPI](https://pypi.org/project/cldk/) using any Python package manager such as [pip](https://pypi.org/project/pip/), [poetry](https://python-poetry.org/), or [uv](https://docs.astral.sh/uv/):
13+
14+
=== "`pip`"
15+
16+
```shell
17+
pip install cldk
18+
```
19+
20+
=== "`poetry`"
21+
22+
```shell
23+
poetry add cldk
24+
```
25+
26+
=== "`uv`"
27+
28+
```shell
29+
uv add cldk
30+
```
31+
32+
## Extra Dependencies
33+
34+
35+
`CLDK` supports program analysis for multiple languages and requires additional dependencies to support specific languages. The following table lists the additional dependencies required for each language:
36+
37+
38+
### Java Analysis
39+
40+
For Java analysis, CLDK relies on a companion project called [`codeanalyzer`](https://github.com/ibm/codenet-minerva-code-analyzer). `codeanalyzer` is a java project and you will therefore need to install the Java Development Kit (JDK) with java version 11 or later.
41+
42+
You can use a package manager like [SDKMAN](https://sdkman.io/) to install the JDK. First, install SDKMAN by running the following command:
43+
44+
- Install SDKMan!
45+
Open your terminal and enter the following command:
46+
47+
```bash
48+
curl -s "https://get.sdkman.io" | bash
49+
```
50+
51+
Follow the on-screen instructions to complete the installation.
52+
53+
- Open a new terminal or source the SDKMan! scripts:
54+
55+
```bash
56+
source "$HOME/.sdkman/bin/sdkman-init.sh"
57+
```
58+
59+
Next, install java 11 or later using SDKMAN:
60+
61+
- You can list all available java versions with:
62+
63+
```bash
64+
sdk list java | grep sem
65+
```
66+
67+
You should see the following:
68+
```bash
69+
Semeru | | 21.0.5 | sem | | 21.0.5-sem
70+
| | 17.0.13 | sem | | 17.0.13-sem
71+
| | 11.0.25 | sem | | 11.0.25-sem
72+
| | 8.0.432 | sem | | 8.0.432-sem
73+
```
74+
75+
- Install Java 11 or above (we'll go with 11.0.2-sem):
76+
77+
```bash
78+
sdk install java 11.0.25-sem
79+
```
80+
81+
- Set Java 11 as the current (or default) Java version:
82+
83+
```bash
84+
sdk [use|default] java 11.0.25-sem
85+
```
86+
87+
- Verify the installation:
88+
89+
```bash
90+
java -version
91+
```
92+
93+
This should output the version of the installed Java.
94+
95+
```bash
96+
openjdk 11.0.25 2024-10-15
97+
IBM Semeru Runtime Open Edition 11.0.25.0 (build 11.0.25+9)
98+
Eclipse OpenJ9 VM 11.0.25.0 (build openj9-0.48.0, JRE 11 Linux amd64-64-Bit Compressed References 20241107_1233 (JIT enabled, AOT enabled)
99+
OpenJ9 - 1d5831436e
100+
OMR - d10a4d553
101+
JCL - edded3f65c based on jdk-11.0.25+9)
102+
```
103+
104+
Finally, to enable building Java projects automatically, you will need to install the `maven` build tool. You can install `maven` using a package manager like `SDKMAN`:
105+
106+
- Install Maven:
107+
108+
```bash
109+
sdk install maven
110+
```
111+
112+
- Make sure `mvn` command is available in the `PATH`. Add the following to your `~/.zshrc`, `~/.bashrc` or `~/.bash_profile`:
113+
114+
```bash
115+
export PATH="$HOME/.sdkman/candidates/maven/current/bin:$PATH"
116+
```
117+
118+
### Python Analysis
119+
120+
For Python analysis as well as to use the CLDK Python SDK, you will need to install the Python programming language with version 3.11 or later. We recommend using a package manager like [pyenv](https://github.com/pyenv/pyenv) to install and manage Python dependencies.
121+
122+
### C/C++ Analysis
123+
124+
CLDK uses LLVM and Clang Python bindings to analyze C/C++ code. The project requires specific versions:
125+
126+
- libclang >= 18.1.1
127+
- clang >= 17.0.6
128+
129+
You can install LLVM and Clang using various package managers depending on your operating system.
130+
131+
=== "macOS"
132+
133+
- Install LLVM 18 using Homebrew
134+
```shell
135+
brew install llvm@18
136+
```
137+
138+
- Add LLVM to your PATH (add this to your ~/.zshrc or ~/.bash_profile)
139+
```shell
140+
export PATH="/usr/local/opt/llvm@18/bin:$PATH"
141+
export LDFLAGS="-L/usr/local/opt/llvm@18/lib"
142+
export CPPFLAGS="-I/usr/local/opt/llvm@18/include"
143+
```
144+
145+
- Verify installation
146+
```shell
147+
clang --version
148+
```
149+
This should output the version of the installed LLVM and Clang.
150+
```shell
151+
Apple clang version 18.1.1
152+
Target: x86_64-apple-darwin21.6.0
153+
Thread model: posix
154+
InstalledDir: /usr/local/opt/llvm@18/bin
155+
```
156+
157+
=== "Ubuntu/Debian"
158+
159+
- Add LLVM repository and install required packages
160+
```shell
161+
wget https://apt.llvm.org/llvm.sh
162+
chmod +x llvm.sh
163+
sudo ./llvm.sh 18
164+
sudo apt-get install llvm-18 llvm-18-dev clang-18 libclang-18-dev
165+
```
166+
167+
- Create symlinks (optional but recommended)
168+
```shell
169+
sudo ln -s /usr/bin/clang-18 /usr/bin/clang
170+
sudo ln -s /usr/bin/llvm-config-18 /usr/bin/llvm-config
171+
```
172+
173+
- Verify installation
174+
```shell
175+
clang --version
176+
```
177+
This should output the version of the installed LLVM and Clang.
178+
```shell
179+
Ubuntu clang version 18.1.1
180+
Target: x86_64-pc-linux-gnu
181+
Thread model: posix
182+
InstalledDir: /usr/bin
183+
```
184+
185+
=== "Red Hat-based Systems (Fedora/CentOS/RHEL)"
186+
187+
- Install LLVM 18 and development packages
188+
```shell
189+
# On Fedora
190+
sudo dnf install llvm18 llvm18-devel clang18 clang18-devel
191+
192+
# On CentOS/RHEL (if needed)
193+
sudo yum install epel-release
194+
sudo yum install llvm18 llvm18-devel clang18 clang18-devel
195+
```
196+
197+
- Create symlinks (optional but recommended)
198+
```shell
199+
sudo ln -s /usr/bin/clang-18 /usr/bin/clang
200+
sudo ln -s /usr/bin/llvm-config-18 /usr/bin/llvm-config
201+
```
202+
203+
- Verify installation
204+
```shell
205+
clang --version
206+
```
207+
This should output the version of the installed LLVM and Clang.
208+
```shell
209+
clang version 18.1.8 (Fedora 18.1.8-5.fc41)
210+
Target: x86_64-redhat-linux-gnu
211+
Thread model: posix
212+
InstalledDir: /usr/bin
213+
Configuration file: /etc/clang18/x86_64-redhat-linux-gnu-clang.cfg
214+
```
215+
216+
217+
### Additional Notes
218+
219+
Some operating systems may require additional development tools:
220+
221+
=== "macOS"
222+
223+
- Make sure you have the Xcode Command Line Tools installed. You can install them using the following command:
224+
225+
```shell
226+
xcode-select --install
227+
```
228+
229+
- Additionally, you may need to install the following packages using Homebrew:
230+
231+
```shell
232+
brew install openssl readline sqlite3 xz zlib tcl-tk libffi
233+
```
234+
235+
=== "Ubuntu/Debian"
236+
237+
- Install the required development tools using the following command:
238+
239+
```shell
240+
sudo apt-get install build-essential python3-dev libssl-dev zlib1g-dev \
241+
libbz2-dev libreadline-dev libsqlite3-dev curl git \
242+
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
243+
```
244+
245+
=== "Red Hat-based Systems (Fedora/CentOS/RHEL)"
246+
247+
- Install the required development tools using the following command:
248+
249+
```shell
250+
sudo dnf group install c-development development-tools gcc make \
251+
patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel\
252+
openssl-devel tk-devel libffi-devel xz-devel
253+
```
254+
255+
256+
257+
## Supported Python Versions
258+
259+
`CLDK` is compatible with Python versions 3.11 and later. The following table lists the supported Python versions and the corresponding `CLDK` versions:
260+
261+
| :fontawesome-brands-python: Python Version | :cldk-logo-white: Compatible `cldk` Versions |
262+
|-------------------------------------------------------------------|--------------------------------------------|
263+
| 3.11 | ≥0.4.0 |

0 commit comments

Comments
 (0)