You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+90-1Lines changed: 90 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -53,8 +53,97 @@ Commands:
53
53
pack Features CodeQL pack management and publication.
54
54
validation Features related to the validation of CodeQL Development Repositories.
55
55
```
56
+
# How to Use QLT
57
+
58
+
QLT is designed to be used mainly in the context of an automation environment, such as actions. Locally, you can use the tool to scaffold common workflows, for example, running unit tests or validating query metadata, and within the actions environment, the workflows that get generated will in turn rely on QLT to perform specialized work related to those tasks.
59
+
60
+
QLT is divided in to **features**. A typical workflow in QLT is that you first `init` a feature, which will install necessary metadata into your repository that is later used to invoke or support the operation of QLT.
61
+
62
+
For example, to initialize unit testing in your repository you can run:
63
+
64
+
```
65
+
qlt test init --use-runner ubuntu-latest --num-threads 4 --language c --automation-type actions
66
+
```
67
+
68
+
Which installs automation for running unit tests for C language queries. Please see the following sections for more information about QLT and its operation as well as see common commands you can use to help manage your CodeQL development.
69
+
70
+
## Assumptions About Repository Layout
71
+
72
+
In order to promote consistency and best practices, QLT takes an opinionated approach to repository layout. These recommendations are based on the experience of our team in deploying CodeQL in a diverse set of environments and we feel offer the best balance of flexibility and functionality.
73
+
74
+
Firstly, it is assumed each repository has a `codeql-workspace.yml` file in it in the root. This file can be created with the following command:
75
+
76
+
```
77
+
qlt query init
78
+
```
79
+
80
+
Next, it is assumed that each repository has a `qlt.conf.json` file in it, which contains information pertaining to the CodeQL version used by the repository. This file can be created with the command:
81
+
82
+
```
83
+
qlt codeql set version
84
+
```
85
+
86
+
Note this uses the default CodeQL version -- you can customize these values on the command line using the `--help` flag and reviewing the available options. Additionally, you may edit the `qlt.conf.json` file directly, though this is not recommended.
87
+
88
+
Next, at the top level it is assumed each language resides in it's own directory. For example, `java` queries should be in a `java` subdirectory. And `c` queries should be in a `c` subdirectory.
89
+
90
+
Within each language, queries should be structured so that each query resides in its own directory and has a matching directory in a test directory. The `src` and `test` directories should both be in their own CodeQL packs.
91
+
92
+
The illustration below details the suggested structure for a repository with two different query packs, each containing a single query.
93
+
94
+
```
95
+
Repo Root
96
+
│ codeql-workspace.yml
97
+
│ qlt.conf.json
98
+
│
99
+
└───cpp
100
+
├───package1
101
+
│ ├───src
102
+
│ │ │ qlpack.yml
103
+
│ │ │
104
+
│ │ └───TestQuery
105
+
│ │ TestQuery.ql
106
+
│ │
107
+
│ └───test
108
+
│ │ qlpack.yml
109
+
│ │
110
+
│ └───TestQuery
111
+
│ TestQuery.cpp
112
+
│ TestQuery.expected
113
+
│ TestQuery.qlref
114
+
│
115
+
└───package2
116
+
├───src
117
+
│ │ qlpack.yml
118
+
│ │
119
+
│ └───TestQuery
120
+
│ TestQuery.ql
121
+
│
122
+
└───test
123
+
│ qlpack.yml
124
+
│
125
+
└───TestQuery
126
+
TestQuery.cpp
127
+
TestQuery.expected
128
+
TestQuery.qlref
129
+
```
130
+
131
+
## Common Tasks / Cookbook
132
+
133
+
**Initialize repo for query development**
134
+
135
+
```
136
+
qlt query init
137
+
```
138
+
139
+
**Initialize CodeQL CI/CD and Unit Testing For Actions**
140
+
141
+
This command will install a number of workflows into your repository which include the necessary workflows for using QLT in your automation environment as well as the workflows for running CodeQL unit tests for the specified language.
142
+
143
+
```
144
+
qlt test init --use-runner ubuntu-latest --num-threads 4 --language c --automation-type actions
0 commit comments