From 8ccec60dba79fcf60737f89805d9b1181d0de0dc Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 27 Sep 2025 18:38:15 +0900 Subject: [PATCH 1/2] adds document directory and getting-start document --- .../getting-started.md | 135 ++++++++++++++++++ .../img/project-overview.svg | 1 + docs/how-to-use-as-libraries/index.md | 5 + 3 files changed, 141 insertions(+) create mode 100644 docs/how-to-use-as-libraries/getting-started.md create mode 100644 docs/how-to-use-as-libraries/img/project-overview.svg create mode 100644 docs/how-to-use-as-libraries/index.md diff --git a/docs/how-to-use-as-libraries/getting-started.md b/docs/how-to-use-as-libraries/getting-started.md new file mode 100644 index 00000000..f756180c --- /dev/null +++ b/docs/how-to-use-as-libraries/getting-started.md @@ -0,0 +1,135 @@ +# Getting Started + +A complete example using ClangSharp is [PInvokeGenerator](../../sources/ClangSharpPInvokeGenerator/), but it's a huge app with lots of options and a bit too much for a tutorial. + +Therefore here describes how to get start to using ClangSharp as C/C++ syntactic analysis library. + +## Project Overview + +[ClangSharp repository](../../) contains several contents and they depend on each other for itself objective. + +When used as a library, [sources/ClangSharp](../../sources/ClangSharp/) will be the main content. + +
+ +
+ +## References Requirements in Your Project + +To get started using ClangSharp, you need append several configurations in your `*.csproj`. + +```xml + + + + Exe + net10.0 + enable + enable + + + linux-x64 + + + + + + + + + + + +``` + +## Sample App to Show C language AST + +To analyze C/C++ source code with ClangSharp, you need to follow these steps: + +1. Creates `CXIndex` instance +2. Creates `CXTranslationUnit` instance with the target source file path +3. Creates `TranslationUnit` instance +4. Traces `Decl` instance from `TranslationUnit.TranslationUnitDecl` + +Following source *Program.cs* is minimum sample to show declarations/statements in C source file. + +```CSharp +using ClangSharp; +using ClangSharp.Interop; + +string sourceFilePath = args[0]; +CXIndex index = CXIndex.Create(); +Span commandLineArgs = ["--language=c",]; +Span unsavedFiles = []; +CXTranslationUnit cxtu = CXTranslationUnit.CreateFromSourceFile(index, sourceFilePath, commandLineArgs, unsavedFiles); +using TranslationUnit tu = TranslationUnit.GetOrCreate(cxtu); +Console.WriteLine($"target source file: {tu.TranslationUnitDecl}"); +PrintDecl(tu.TranslationUnitDecl, " "); + + +static void PrintDecl(Decl decl, string indent) +{ + Console.WriteLine($"{indent}[decl][{decl.Location}] {decl.DeclKindName} {decl.Spelling}"); + indent += " "; + foreach (var child in decl.Decls) + { + PrintDecl(child, indent); + } + if(decl.Body is { } body) + { + PrintStmt(body, indent); + } +} + +static void PrintStmt(Stmt stmt, string indent) +{ + Console.WriteLine($"{indent}[stmt][{stmt.Location}] {stmt.StmtClass} {stmt.Spelling}"); + indent += " "; + foreach (var child in stmt.Children) + { + PrintStmt(child, indent); + } +} +``` + +Running this app will produce the following results. + +- command + + ```bash + dotnet run -- main.c + ``` + +- input source file `./main.c` + + ```c + #include + + int main() { + printf("Hello, World!\n"); + return 0; + } + ``` + +- console output + + ```plaintext + target source file: ./main.c + [decl][Line 0, Column 0 in ] TranslationUnit ./main.c + [decl][Line 0, Column 0 in ] Typedef __int128_t + [decl][Line 0, Column 0 in ] Typedef __uint128_t + [decl][Line 0, Column 0 in ] Typedef __NSConstantString + [decl][Line 0, Column 0 in ] Typedef __builtin_ms_va_list + [decl][Line 0, Column 0 in ] Typedef __builtin_va_list + [decl][Line 3, Column 5 in ./main.c] Function main + [stmt][Line 3, Column 12 in ./main.c] CX_StmtClass_CompoundStmt + [stmt][Line 4, Column 5 in ./main.c] CX_StmtClass_FirstCallExpr printf + [stmt][Line 4, Column 5 in ./main.c] CX_StmtClass_FirstCastExpr printf + [stmt][Line 4, Column 5 in ./main.c] CX_StmtClass_DeclRefExpr printf + [stmt][Line 4, Column 12 in ./main.c] CX_StmtClass_FirstCastExpr + [stmt][Line 4, Column 12 in ./main.c] CX_StmtClass_FirstCastExpr + [stmt][Line 4, Column 12 in ./main.c] CX_StmtClass_StringLiteral "Hello, World!\n" + [stmt][Line 5, Column 5 in ./main.c] CX_StmtClass_ReturnStmt + [stmt][Line 5, Column 12 in ./main.c] CX_StmtClass_IntegerLiteral + [decl][Line 4, Column 5 in ./main.c] Function printf + ``` diff --git a/docs/how-to-use-as-libraries/img/project-overview.svg b/docs/how-to-use-as-libraries/img/project-overview.svg new file mode 100644 index 00000000..dbdf2313 --- /dev/null +++ b/docs/how-to-use-as-libraries/img/project-overview.svg @@ -0,0 +1 @@ +
<<C++ sources>>
sources/libClangSharp
<<C++ sources>>...
<<library>>
sources/ClangSharp.Interop
<<library>>...
<<library>>
sources/ClangSharp
<<library>>...
<<library>>
sources/ClangSharp.PInvokeGenerator
<<library>>...
<<console app>>
sources/ClangSharpPInvokeGenerator
<<console app>>...
<<unit test>>
tests/ClangSharp.PInvokeGenerator.UnitTest
<<unit test>>...
<<unit test>>
sources/ClangSharp.UnitTests
<<unit test>>...
generate
generateText is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to-use-as-libraries/index.md b/docs/how-to-use-as-libraries/index.md new file mode 100644 index 00000000..a9b3a01a --- /dev/null +++ b/docs/how-to-use-as-libraries/index.md @@ -0,0 +1,5 @@ +# Index - how to use ClangSharp as libraris + +ClangSharp can be used as libraries for C/C++ syntactic analysis. + +- [Getting Started](./getting-started.md) From dc373bd7b5cce5c333ac45c3f6b10547a983ea4e Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 27 Sep 2025 18:38:32 +0900 Subject: [PATCH 2/2] updates README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index df4ca5f2..35df8f34 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,10 @@ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install -DPATH_TO_LLV make install ``` +### Using as Libraries + +Please refer to [how to use ClangSharp as libraris](./docs/how-to-use-as-libraries/index.md) to learn how to use as libraries. + ### Generating Bindings This program will take a given set of C or C++ header files and generate C# bindings from them. It is still a work-in-progress and not every declaration can have bindings generated today (contributions are welcome).