Skip to content

Commit 84e7dc5

Browse files
Update CONTRIBUTING.md
1 parent 47c3e9c commit 84e7dc5

File tree

1 file changed

+51
-3
lines changed

1 file changed

+51
-3
lines changed

CONTRIBUTING.md

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -161,13 +161,12 @@ these steps:
161161
3. Build dpctl with code coverage support.
162162

163163
```bash
164-
python setup.py develop --coverage=True
165-
pytest -q -ra --disable-warnings --cov dpctl --cov-report term-missing --pyargs dpctl -vv
164+
python scripts/gen_coverage.py --oneapi
166165
coverage html
167166
```
168167

169168
Note that code coverage builds the C sources with debug symbols. For this
170-
reason, the coverage flag is only available with the `develop` mode of
169+
reason, the coverage script builds the package in `develop` mode of
171170
`setup.py`.
172171

173172
The coverage results for the C and Python sources will be printed to the
@@ -191,3 +190,52 @@ these steps:
191190
> ```
192191
> The error is related to the `tcl` package. You should uninstall the `tcl`
193192
> package to resolve the error.
193+
194+
## Error Reporting and Logging
195+
196+
The SyclInterface library responds to `DPCTL_VERBOSITY` environment variable that controls the severity level of errors printed to console.
197+
One can specify one of the following severity levels (in increasing order of severity): `warning` and `error`.
198+
199+
```bash
200+
export DPCTL_VERBOSITY=warning
201+
```
202+
203+
Messages of a given severity are shown not only in the console for that severity, but also for the higher severity. For example, the severity level `warning` will output severity errors for `error` and `warning` to the console.
204+
205+
### Optional use of the Google logging library (glog)
206+
207+
Dpctl's error handler for libsyclinterface can be optionally configured to use [glog](https://github.com/google/glog). To use glog, follow the following steps:
208+
209+
1. Install glog package of the latest version (0.5.0)
210+
211+
```bash
212+
conda install glog
213+
```
214+
2. Build dpctl with glog support
215+
216+
```bash
217+
python scripts/build_locally.py --oneapi --glog
218+
```
219+
220+
3. Use `dpctl._diagnostics.syclinterface_diagnostics(verbosity="warning", log_dir=None)` context manager to switch library diagnostics on for a block of Python code.
221+
Use `DPCTLService_InitLogger` and `DPCTLService_ShutdownLogger` library C functions during library development to initialize the Google's logging library and de-initialize accordingly
222+
223+
```python
224+
from dpctl._diagnostics import syclinterface_diagnostics
225+
import dpctl
226+
227+
with syclinterface_diagnostics():
228+
code
229+
```
230+
231+
```c
232+
DPCTLService_InitLogger(const char *app_name, const char *log_dir);
233+
DPCTLService_ShutdownLogger();
234+
```
235+
236+
- `*app_name` - name of the executable file (prefix for logs of various levels).
237+
- `*log_dir` - directory path for writing log files. Specifying `NULL` results in logging to ``std::cerr``.
238+
239+
> **_NOTE:_**
240+
>
241+
> If `InitGoogleLogging` is not called before first use of glog, the library will self-initialize to `logtostderr` mode and log files will not be generated.

0 commit comments

Comments
 (0)