mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
7a3a0a9e23
Adds a tool `swift-symbolgraph-extract` that reads an existing Swift module and prints a platform- and language-agnostic JSON description of the module, primarly for documentation. Adds a small sub-library `SymbolGraphGen` which houses the core implementation for collecting relevant information about declarations. The main entry point is integrated directly into the driver as a mode: the tool is meant to be run outside of the normal edit-compile-run/test workflow to avoid impacting build times. Along with common options for other tools, unique options include `pretty-print` for debugging, and a `minimum-access-level` options for including internal documentation. A symbol graph is a directed graph where the nodes are symbols in a module and the edges are relationships between them. For example, a `struct S` may have a member `var x`. The graph would have two nodes for `S` and `x`, and one "member-of" relationship edge. Other relationship kinds include "inherits-from" or "conforms to". The data format for a symbol graph is still under development and may change without notice until a specificiation and versioning scheme is published. Various aspects about a symbol are recorded in the nodes, such as availability, documentation comments, or data needed for printing the shapes of declarations without having to understand specifics about the langauge. Implicit and public-underscored stdlib declarations are not included by default. rdar://problem/55346798
57 lines
1.7 KiB
C++
57 lines
1.7 KiB
C++
//===--- SymbolGraphGen.cpp - Symbol Graph Generator Entry Point ----------===//
|
|
//
|
|
// This source file is part of the Swift.org open source project
|
|
//
|
|
// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See https://swift.org/LICENSE.txt for license information
|
|
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#include "llvm/Support/JSON.h"
|
|
#include "llvm/Support/Path.h"
|
|
#include "swift/AST/Module.h"
|
|
#include "swift/SymbolGraphGen/SymbolGraphGen.h"
|
|
|
|
#include "SymbolGraphASTWalker.h"
|
|
|
|
using namespace swift;
|
|
using namespace symbolgraphgen;
|
|
|
|
// MARK: - Main Entry Point
|
|
|
|
/// Emit a symbol graph JSON file for a `ModuleDecl`.
|
|
int
|
|
symbolgraphgen::emitSymbolGraphForModule(ModuleDecl *M,
|
|
const SymbolGraphOptions &Options) {
|
|
SymbolGraphASTWalker Walker(*M, Options);
|
|
SmallVector<Decl *, 64> ModuleDecls;
|
|
M->getDisplayDecls(ModuleDecls);
|
|
|
|
llvm::errs() << ModuleDecls.size()
|
|
<< " top-level declarations in this module.\n";
|
|
|
|
for (auto *Decl : ModuleDecls) {
|
|
Walker.walk(Decl);
|
|
}
|
|
|
|
llvm::errs()
|
|
<< "Found " << Walker.Graph.Nodes.size() << " symbols and "
|
|
<< Walker.Graph.Edges.size() << " relationships.\n";
|
|
|
|
std::error_code Error;
|
|
llvm::raw_fd_ostream OS(Options.OutputPath, Error, llvm::sys::fs::FA_Write);
|
|
if (Error) {
|
|
llvm::errs() << "Couldn't open output file for writing: "
|
|
<< Error.message() << "\n";
|
|
return EXIT_FAILURE;
|
|
}
|
|
|
|
llvm::json::OStream J(OS, Options.PrettyPrint ? 2 : 0);
|
|
Walker.Graph.serialize(Walker, J);
|
|
|
|
return EXIT_SUCCESS;
|
|
}
|