diff --git a/README.rst b/README.rst index ddc164e1fc..9da7b7c5cb 100644 --- a/README.rst +++ b/README.rst @@ -1,23 +1,28 @@ ================ -ScanCode toolkit +ScanCode Toolkit ================ -A typical software project often reuses hundreds of third-party packages. -License and packages, dependencies and origin information is not always easy to -find and not normalized: ScanCode discovers and normalizes this data for you. +ScanCode Toolkit is a set of code scanning tools that detect the origin (copyrights), license and vulnerabilities of code, packages and dependencies in a codebase. ScanCode Toolkit is an `AboutCode project `_. -Read more about ScanCode here: https://scancode-toolkit.readthedocs.io/. +Why Use ScanCode Toolkit? +========================= + +ScanCode Toolkit is the leading tool in scanning depth and accuracy, used by hundreds of software teams. You can use ScanCode Toolkit as a command line tool or as a library. -Check out the code at https://github.com/nexB/scancode-toolkit +Getting Started +=============== -Discover also: +Instructions to get you up and running on your local machine are at `Getting Started `_ -- The ScanCode.io server project here: https://scancodeio.readthedocs.io -- The ScanCode Workbench project for visualization of scancode results data: - https://github.com/nexB/scancode-workbench -- Other companion SCA projects for code origin, license and security analysis - here: https://aboutcode.org +The ScanCode Toolkit documentation also provides: +- prerequisites for installing the software. +- instructions guiding you to start scanning code. +- a comprehensive guide to the command line options. +- tutorials that provide hands-on guidance to ScanCode features. +- how to expand ScanCode Licenses and Detection Rules with your own data. +- how to generate Attribution from a ScanCode scan. +- guidelines for contributing to code development. Build and tests status ====================== @@ -31,13 +36,10 @@ compabitility with multiple versions of Windows, Linux and macOS. | |azure| | |docs-rtd| | |docs-github-actions| | |release-github-actions| | +------------+--------------+-------------------------+----------------------------+ +Benefits of ScanCode +==================== -Why use ScanCode? -================= - -- As a **standalone command-line tool**, ScanCode is **easy to install**, run, - and embed in your CI/CD processing pipeline. - It runs on **Windows, macOS, and Linux**. +- ScanCode is heavily **tested** with an automated test suite of over **30,000 tests**. - ScanCode is **used by several projects and organizations** such as the `Eclipse Foundation `_, @@ -49,6 +51,14 @@ Why use ScanCode? `RedHat Fabric8 analytics `_, and many more. +- You can also organize and run ScanCode server-side with the + companion `ScanCode.io web app `_ + to organize and store multiple scan projects including scripted scanning pipelines. + +- As a **standalone command-line tool**, ScanCode is **easy to install**, run, + and embed in your CI/CD processing pipeline. + It runs on **Windows, macOS, and Linux**. + - ScanCode detects licenses, copyrights, package manifests, direct dependencies, and more both in **source code** and **binary** files and is considered as the best-in-class and reference tool in this domain, re-used as the core tools for @@ -66,187 +76,32 @@ Why use ScanCode? - You can save your scan results as **JSON, YAML, HTML, CycloneDX or SPDX** or even create your own format with Jinja templates. -- You can also organize and run ScanCode server-side with the - companion `ScanCode.io web app `_ - to organize and store multiple scan projects including scripted scanning pipelines. - -- ScanCode output data can be easily visualized and analysed using the - `ScanCode Workbench `_ desktop app. - -- ScanCode is **actively maintained**, has a **growing users and contributors - community**. - -- ScanCode is heavily **tested** with an automated test suite of over **20,000 tests**. - -- ScanCode has an extensive and growing documentation. - - ScanCode can process packages, build manifest and lockfile formats to collect - Package URLs and extract metadata: Alpine packages, BUCK files, ABOUT files, - Android apps, Autotools, Bazel, JavaScript Bower, Java Axis, MS Cab, - Rust Cargo, Cocoapods, Chef Chrome apps, PHP Composer and composer.lock, - Conda, CPAN, Debian, Apple dmg, Java EAR, WAR, JAR, FreeBSD packages, - Rubygems gemspec, Gemfile and Gemfile.lock, Go modules, Haxe packages, - InstallShield installers, iOS apps, ISO images, Apache IVY, JBoss Sar, - R CRAN, Apache Maven, Meteor, Mozilla extensions, MSI installers, - JavaScript npm packages, package-lock.json, yarn.lock, NSIS Installers, - NuGet, OPam, Cocoapods, Python PyPI setup.py, setup.cfg, and - several related lockfile formats, semi structured README - files such as README.android, README.chromium, README.facebook, README.google, - README.thirdparty, RPMs, Shell Archives, Squashfs images, Java WAR, Windows - executables and the Windows registry - and a few more. See `all available package parsers `_ + Package URLs and extract metadata. See all available `package parsers + `_ for the exhaustive list. -See our `roadmap `_ -for upcoming features. - - -Documentation -============= - -The ScanCode documentation is hosted at -`scancode-toolkit.readthedocs.io `_. - -If you are new to visualization of scancode results data, start with our -`newcomer `_ page. - -If you want to compare output changes between different versions of ScanCode, -or want to look at scans generated by ScanCode, review our -`reference scans `_. - -Other Important Documentation Pages: - -- A `synopsis `_ - of ScanCode command line options. - -- Tutorials on: - - - `How to run a scan `_ - - `How to visualize scan results `_ - -- An exhaustive list of `all available options `_ - -- Documentation on `Contributing to Code Development `_ - -- Documentation on `Plugin Architecture `_ - -- `FAQ `_ - -See also https://aboutcode.org for related companion projects and tools. - - -Installation -============ - -Before installing ScanCode make sure that you have installed the prerequisites -properly. This means installing Python 3.13 for x86/64 architectures. -We support Python 3.10, 3.11, 3.12 and 3.13. - -See `prerequisites `_ -for detailed information on the support platforms and Python versions. - -There are a few common ways to `install ScanCode `_. - -- `**Installation as an application: Install Python 3.13, download a release archive, extract and run**. - `_ - This is the recommended installation method. - -- `Development installation from source code using a git clone - `_ - -- `Development installation as a library with "pip install scancode-toolkit" - `_ - [Note that this is not supported on arm64 machines] - -- `Run in a Docker container with a git clone and "docker run" - `_ - -- In Fedora 40+ you can `dnf install scancode-toolkit` - - -Quick Start -=========== - -After ScanCode is installed successfully you can run an example scan printed on screen as JSON:: - - scancode -clip --json-pp - samples - -Follow the `How to Run a Scan `_ -tutorial to perform a basic scan on the ``samples`` directory distributed by -default with ScanCode. - -See more command examples:: - - scancode --examples - -See `How to select what will be detected in a scan -`_ -and `How to specify the output format `_ -for more information. - -You can also refer to the `command line options synopsis -`_ -and an exhaustive list of `all available command line options -`_. - - -Archive extraction -================== - -By default ScanCode does not extract files from tarballs, zip files, and -other archives as part of the scan. The archives that exist in a codebase -must be extracted before running a scan: `extractcode` is a bundled utility -behaving as a mostly-universal archive extractor. For example, this command will -recursively extract the mytar.tar.bz2 tarball in the mytar.tar.bz2-extract -directory:: - - ./extractcode mytar.tar.bz2 - -See `all extractcode options `_ -and `how to extract archives `_ for details. - - Support ======= -If you have a problem, a suggestion or found a bug, please enter a ticket at: -https://github.com/nexB/scancode-toolkit/issues +If you have a specific problem, suggestion or bug, please submit a +`GitHub issue `_. -For discussions and chats, we have: +For quick questions or socializing, join the AboutCode community discussions on `Slack `_. -* an official Gitter channel for `web-based chats - `_. - Gitter is now accessible through `Element `_ - or an `IRC bridge `_. - There are other AboutCode project-specific channels available there too. - -* The discussion channel for `scancode `_ - specifically aimed at users and developers using scancode-toolkit. - -Source code and downloads -========================= - -* https://github.com/aboutcode-org/scancode-toolkit/releases -* https://github.com/aboutcode-org/scancode-toolkit.git -* https://pypi.org/project/scancode-toolkit/ -* https://github.com/aboutcode-org/scancode-thirdparty-src.git -* https://github.com/aboutcode-org/scancode-plugins.git -* https://github.com/aboutcode-org/thirdparty-packages.git +Interested in commercial suppport? Contact the `AboutCode team `_. License ======= -* Apache-2.0 as the overall license -* CC-BY-4.0 for reference datasets (initially was in the Public Domain). -* Multiple other secondary permissive or copyleft licenses (LGPL, MIT, +* `Apache-2.0 `_ is the overall license. +* `CC-BY-4.0 `_ applies to reference datasets. +* There are multiple secondary permissive or copyleft licenses (LGPL, MIT, BSD, GPL 2/3, etc.) for third-party components and test suite code and data. - -See the NOTICE file and the .ABOUT files that document the origin and license of +See the `NOTICE file `_ and the `.ABOUT files `_ that document the origin and license of the third-party code used in ScanCode for more details. - - .. |azure| image:: https://dev.azure.com/nexB/scancode-toolkit/_apis/build/status/nexB.scancode-toolkit?branchName=develop :target: https://dev.azure.com/nexB/scancode-toolkit/_build/latest?definitionId=1&branchName=develop :alt: Azure tests status (Linux, macOS, Windows) @@ -265,7 +120,7 @@ the third-party code used in ScanCode for more details. Acknowledgements, Funding, Support and Sponsoring --------------------------------------------------------- +================================================= This project is funded, supported and sponsored by: @@ -394,3 +249,5 @@ Communications Networks, Content and Technology under grant agreement No 1010695 :target: https://nlnet.nl/discovery/ :height: 40 :alt: NGI Discovery logo + +**End of ScanCode Toolkit README**