Skip to content

Update README #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update README #8

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
37f5d0a
Update README for example of use and description of how to verify cus…
knewbury01 Apr 25, 2024
3455af7
Fix small formatting in README
knewbury01 Apr 25, 2024
698370a
Update README.md
knewbury01 Apr 25, 2024
1a0fc99
Update README.md
knewbury01 Apr 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,20 @@ You can see the packs available in your workspace by running `codeql pack ls --
With both a CodeQL bundle and a CodeQL workspace you can create a bundle with the command:

```bash
codeql-bundle --bundle <path-to-bundle> --output codeql-custom-bundle.tar.gz --workspace <path-to-workspace> --log INFO <packs>
codeql-bundle --bundle <path-to-bundle> --output codeql-custom-bundle.tar.gz --workspace <path-to-workspace-file> --log INFO <packs>
```

If the source bundle is the platform agnostic bundle then you can create platform specific bundles to reduce the size of the used bundle(s).
The following example creates platform specific bundles for all the currently supported platforms.

```bash
codeql-bundle --bundle <path-to-platform-agnostic-bundle> --output <path-to-bundles-dir> --workspace <path-to-workspace> --log INFO -p linux64 -p osx64 -p win64 <packs>
codeql-bundle --bundle <path-to-platform-agnostic-bundle> --output <path-to-bundles-dir> --workspace <path-to-workspace-file> --log INFO -p linux64 -p osx64 -p win64 <packs>
```

An example of creation of a custom bundle for OSX containing a customization pack with the name `foo/cpp-customizations` would look as follows:

```bash
codeql-bundle --bundle codeql-bundle-osx64.tar.gz --output codeql-custom-bundle --workspace codeql-workspace.yml --log INFO foo/cpp-customizations -p osx64
```

## CodeQL customization packs
Expand All @@ -63,6 +69,18 @@ This example targets the C/C++ language, but you can use this for any supported
3. Add a dependency on `codeql/cpp-all` with `codeql pack add --dir=cpp-customizations codeql/cpp-all`
4. Implement the customizations module with `mkdir -p cpp-customizations/foo/cpp_customizations && echo "import cpp" > cpp-customizations/foo/cpp_customizations/Customizations.qll`

To verify that the customization pack was correctly imported one can check that it is listed as a dependency in the standard library pack it was added to. It will look as follows (for example for a pack named `foo/cpp-customizations` added to `codeql/cpp-all`):
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was there a situation where a customization pack was not added?

Perhaps we can add more validation to determine if something looks like a customization pack, but isn't one to warn the user?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if the directory naming schema "where any character - in the scope or package_name is replaced with _"
listed in the readme is not observed , ie if the name accidentally has the - not the _ it will still create the bundle and it will contain the customization pack but will not do the import into the std lib pack (ie might look sorta correct but will not be usable)

I do know this detail is bold highlighted in the action readme, ... I still have missed it 2/2 times on my own CLI usage attempts 😅 (which is maybe a me thing, but also again, if the user is still only getting familiar with CodeQL overall, making them memorize this specific step is less ideal)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tho I would be happy to see a validation step / instead/in addition to the addition to the readme!


#### **`codeql/qlpacks/codeql/cpp-all/<version-number-standard-library-used>/qlpack.yml`**
```
...
dependencies:
...
...
foo/cpp-customizations: 0.0.1
...
```

## Limitations

- The customization pack must directly rely on a CodeQL language pack.
Expand Down