Skip to content

Commit 1ee7fdf

Browse files
jeremyfelderjeremyfelder
committed
Adds a few starter cursor rules
1 parent 611883f commit 1ee7fdf

4 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎.cursor/rules/add-feature-go-wrapper.mdc‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
description: How to add a new feature to go wrappers
3+
globs:
4+
alwaysApply: false
5+
---
6+
# Add New Feature to Go Wrappers
7+
8+
This checklist outlines the steps required to add support for a new ICICLE feature (e.g., Sumcheck, Pairing) to the Go wrappers generator. Replace `<FeatureName>` with the PascalCase name of the feature (e.g., `Sumcheck`) and `<featurename>` with the lowercase version (e.g., `sumcheck`).
9+
10+
**Context Files:**
11+
12+
* `@wrappers/golang/internal/generator/config/config.go`
13+
* `@wrappers/golang/internal/generator/config/fields.go` (or similar config initialization file)
14+
* `@wrappers/golang/internal/generator/config/curves.go` (or similar config initialization file)
15+
* `@wrappers/golang/internal/generator/main.go`
16+
* `@icicle/cmake/features.cmake`
17+
* (New) `@wrappers/golang/internal/generator/<featurename>/generate.go`
18+
* (New) `@wrappers/golang/internal/generator/<featurename>/templates/<featurename>.go.tmpl`
19+
* (New) `@wrappers/golang/internal/generator/<featurename>/templates/<featurename>_test.go.tmpl`
20+
* (New) `@wrappers/golang/internal/generator/<featurename>/templates/<featurename>.h.tmpl`
21+
22+
**Checklist:**
23+
24+
* [ ] **Update Config Structs:**
25+
* In `wrappers/golang/internal/generator/config/config.go`:
26+
* Add `Supports<FeatureName> bool` field to `FieldData` struct.
27+
* Add `Supports<FeatureName> bool` field to `CurveData` struct.
28+
29+
* [ ] **Update Config Initialization:**
30+
* In the files under `wrappers/golang/internal/generator/config/` where `FieldData` and `CurveData` instances are created (e.g., `fields.go`, `curves.go`):
31+
* Initialize the `Supports<FeatureName>` field for each field/curve based on its capabilities, typically by checking `icicle/cmake/features.cmake`.
32+
33+
* [ ] **Update Main Generator (`main.go`):**
34+
* In `wrappers/golang/internal/generator/main.go`:
35+
* Update the feature parsing logic (likely reading from `features.cmake`) to recognize the new `<FeatureName>` feature string.
36+
* Set the `Supports<FeatureName>` flag accordingly in the `CurveData` or `FieldData` instances being processed.
37+
* Add the import statement for the new generator package: `_ "github.com/ingonyama-zk/icicle/v3/wrappers/golang/internal/generator/<featurename>"`.
38+
* Within the loops processing curves and fields, add a conditional call to the new feature's generator:
39+
```go
40+
if curve.Supports<FeatureName> { // or field.Supports<FeatureName>
41+
<featurename>.Generate(outputDir, curve.Curve, ...) // Pass necessary arguments
42+
}
43+
```
44+
45+
* [ ] **Create Feature Generator Directory:**
46+
* Create the directory: `wrappers/golang/internal/generator/<featurename>/`
47+
48+
* [ ] **Create Generator Logic File:**
49+
* Create the file: `wrappers/golang/internal/generator/<featurename>/generate.go`.
50+
* Define a `Generate` function responsible for executing templates.
51+
* Define a data struct (e.g., `<FeatureName>Data`) to pass information to the templates.
52+
* Define constants for the template file paths (pointing into the `templates` subdirectory).
53+
* Implement the `Generate` function to parse templates and call `generator_utils.GenerateFile` for each template (`.go`, `_test.go`, `.h`).
54+
55+
* [ ] **Create Templates Directory:**
56+
* Create the subdirectory: `wrappers/golang/internal/generator/<featurename>/templates/`
57+
58+
* [ ] **Create Go Template File:**
59+
* Create the Go code template: `wrappers/golang/internal/generator/<featurename>/templates/<featurename>.go.tmpl`.
60+
* Implement the Go bindings using CGO, referencing functions defined in the corresponding `.h.tmpl`. Use template variables (e.g., `{{.Field}}`, `{{.PackageName}}`) passed from `generate.go`.
61+
62+
* [ ] **Create Test Template File:**
63+
* Create the Go test template: `wrappers/golang/internal/generator/<featurename>/templates/<featurename>_test.go.tmpl`.
64+
* Add placeholder test functions (e.g., `Test<FeatureName>Functionality`, `Test<FeatureName>Serialization`) using the `testing` package and ideally `stretchr/testify`. Mark tests as skipped initially.
65+
66+
* [ ] **Create Header Template File:**
67+
* Create the C header template: `wrappers/golang/internal/generator/<featurename>/templates/<featurename>.h.tmpl`.
68+
* Define the necessary C function signatures, structs (like FFI-safe configs), typedefs, and includes required for the CGO calls in the `.go.tmpl` file. Use template variables as needed.
69+
70+
* [ ] **Run Generator:**
71+
* Execute `go generate` within the `wrappers/golang/internal/generator/` directory to test the changes and generate the new wrapper files.
72+
73+
* [ ] **Implement TODOs:**
74+
* Fill in any `// TODO:` comments left in the generated Go code or templates, especially around complex CGO conversions, memory management, and test logic.

‎.cursor/rules/cursor-rules.mdc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
description: How to add or edit Cursor rules in our project
3+
globs:
4+
alwaysApply: false
5+
---
6+
# Cursor Rules Location
7+
8+
How to add new cursor rules to the project
9+
10+
1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
11+
```
12+
.cursor/rules/
13+
├── your-rule-name.mdc
14+
├── another-rule.mdc
15+
└── ...
16+
```
17+
18+
2. Follow the naming convention:
19+
- Use kebab-case for filenames
20+
- Always use .mdc extension
21+
- Make names descriptive of the rule's purpose
22+
23+
3. Directory structure:
24+
```
25+
PROJECT_ROOT/
26+
├── .cursor/
27+
│ └── rules/
28+
│ ├── your-rule-name.mdc
29+
│ └── ...
30+
└── ...
31+
```
32+
33+
4. Never place rule files:
34+
- In the project root
35+
- In subdirectories outside .cursor/rules
36+
- In any other location
37+
38+
5. Cursor rules have the following structure:
39+
40+
````
41+
---
42+
description: Short description of the rule's purpose
43+
globs: optional/path/pattern/**/*
44+
alwaysApply: false
45+
---
46+
# Rule Title
47+
48+
Main content explaining the rule with markdown formatting.
49+
50+
1. Step-by-step instructions
51+
2. Code examples
52+
3. Guidelines
53+
````

‎.cursor/rules/main.mdc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
# ICICLE - Main Rule Index
7+
8+
This document serves as the central index for all active Cursor rules within this repository, organized by category. These rules define processes, structures, and guidelines for development.
9+
10+
In general, ICICLE should be upper case unless being used in code.
11+
12+
When updating this file, do not change when this file is ap
13+
14+
## Core & General
15+
16+
Fundamental project structure, setup, and general development guidelines.
17+
18+
| Rule File | Description |
19+
| :--------------------------------- | :---------------------------------------------------------- |
20+
| @cursor-rules.mdc | How to add or edit Cursor rules in our project |
21+
| @project-structure.mdc | Project structure and file organization guidelines |
22+
23+
## Frontend and wrapper languages
24+
25+
Guidelines for building frontend libraries and wrapper languages like Rust and Golang.
26+
27+
| Rule File | Description |
28+
| :--------------------------------- | :---------------------------------------------------------- |
29+
| @add-feature-go-wrapper.mdc | Guidelines for adding new feature in Go wrapper |
30+
31+
## Backends
32+
33+
Guidelines for implementing backend logic.
34+
35+
| Rule File | Description |
36+
| :--------------------------------- | :---------------------------------------------------------- |
37+
38+
## Testing and CI
39+
40+
Guidelines for application testing.
41+
42+
| Rule File | Description |
43+
| :--------------------------------- | :---------------------------------------------------------- |

‎.cursor/rules/project-structure.mdc‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
description: Project structure and file organization guidelines
3+
globs:
4+
alwaysApply: false
5+
---
6+
# Project Structure
7+
8+
The ICICLE project is made up of three pieces:
9+
- The frontend
10+
- A backend
11+
- A wrapper language
12+
13+
The frontend is a cpp implementation that includes API definitions, object definitions, interfaces for backends to implement, some core logic for fields and arithmetic, and a dispatcher class that routes API calls to the correct backend implementation.
14+
15+
Each backend, located under `icicle/backend`, implements features according to the frontend's interfaces
16+
17+
Each wrapper language, located under `wrappers/`, implements bindings for that language to the frontend's externed C API which wraps the c++ implementation
18+
19+
## Directory Structure
20+
21+
- Front cpp implementation is in the `icicle` folder
22+
- Wrapper languages are in the `wrappers` folder
23+
- Backends are in `icicle/backend` folder
24+
- Docs are in `docs` folder
25+
26+
```tree
27+
.
28+
├── docs # Developer documentation
29+
│ ├── docs # Developer documentation for the next release
30+
│ │ └── icicle #
31+
│ │ ├── golang-bindings # Golang bindings docs
32+
│ │ ├── primitives # Cpp docs
33+
│ │ ├── programmers_guide # Guides for using ICICLE
34+
│ │ └── rust-bindings # Rust bindings docs
35+
│ ├── versioned_docs # Previous versions' docs
36+
│ └── versioned_sidebars # Previous versions' nav menu
37+
├── examples # Examples using ICICLE APIs
38+
│ ├── c++ # Examples using ICICLE c++ API
39+
│ ├── golang # Examples using ICICLE golang API
40+
│ └── rust # Examples using ICICLE rust API
41+
├── icicle # Main c++ implementation of ICICLE
42+
│ ├── backend # Backends location
43+
│ │ ├── cpu # CPU Backend
44+
│ │ └── <other> # Potentially other local backends
45+
│ ├── cmake # Cmake configuration files
46+
│ ├── include # includes directory for ICICLE
47+
│ │ └── icicle
48+
│ │ ├── api
49+
│ │ ├── backend
50+
│ │ ├── curves
51+
│ │ ├── fields
52+
│ │ ├── fri
53+
│ │ ├── hash
54+
│ │ ├── math
55+
│ │ ├── merkle
56+
│ │ ├── pairing
57+
│ │ ├── polynomials
58+
│ │ ├── program
59+
│ │ ├── rings
60+
│ │ ├── sumcheck
61+
│ │ └── utils
62+
│ ├── src # source directory for ICICLE
63+
│ │ ├── curves
64+
│ │ ├── fields
65+
│ │ ├── fri
66+
│ │ ├── hash
67+
│ │ ├── polynomials
68+
│ │ ├── program
69+
│ │ ├── rings
70+
│ │ ├── sumcheck
71+
│ │ └── symbol
72+
│ └── tests # Tests directory for ICICLE using gtest
73+
├── scripts # Scripts directory
74+
│ ├── hooks # Git hooks scripts
75+
│ ├── python # python scripts
76+
│ └── release # Buidling releases
77+
└── wrappers # Wrapper languages
78+
├── golang # Golang bindings
79+
│ ├── core # Core package
80+
│ ├── curves
81+
│ ├── fields
82+
│ ├── hash
83+
│ ├── internal # Code templates and generation
84+
│ ├── merkle-tree
85+
│ └── runtime # Bindings for device and runtime
86+
└── rust # Rust bindings
87+
├── icicle-core # Core package
88+
├── icicle-curves
89+
├── icicle-fields
90+
├── icicle-hash
91+
├── icicle-rings
92+
└── icicle-runtime # Bindings for device and runtime
93+
```
94+
95+
## New Docs
96+
97+
- Create new docs in `docs/docs`
98+

0 commit comments

Comments
 (0)