|
| 1 | +# GPU-memory-access-visualization |
| 2 | + |
| 3 | +This folders contains the project which generates the HTML template. |
| 4 | + |
| 5 | +The overall application with a reduction dataset loaded in looks like this: |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | + |
| 10 | +It is build on the following technologies (those are the most important ones): |
| 11 | + |
| 12 | +* TypeScript |
| 13 | +* [Svelte](https://svelte.dev/) |
| 14 | +* [Skeleton UI Framework](https://skeleton.dev) |
| 15 | +* [Tailwind CSS](https://tailwindcss.com/) |
| 16 | +* [Vite](https://vitejs.dev/) |
| 17 | + |
| 18 | +More information about the packages and their uses in the section below. |
| 19 | + |
| 20 | +But first how to use and install the project. |
| 21 | + |
| 22 | +### Table of Content |
| 23 | + |
| 24 | +<!-- TOC --> |
| 25 | +* [GPU-memory-access-visualization](#gpu-memory-access-visualization) |
| 26 | + * [Table of Content](#table-of-content) |
| 27 | + * [Using the project](#using-the-project) |
| 28 | + * [Installing the project](#installing-the-project) |
| 29 | + * [Developing](#developing) |
| 30 | + * [Building](#building) |
| 31 | + * [More details about the used packages and their files](#more-details-about-the-used-packages-and-their-files) |
| 32 | + * [Entrypoint for Development](#entrypoint-for-development) |
| 33 | +<!-- TOC --> |
| 34 | + |
| 35 | +## Using the project |
| 36 | + |
| 37 | +To use the project, you don't need to do anything else. There should be a pre-built HTML file ready for you to use. |
| 38 | + |
| 39 | +Besides the text below, there is an [additional Documentation file here](FEATURES.md), which showcases the individual features with images. |
| 40 | + |
| 41 | +To then make use of that file the suggested way is to generate static `.json` data files with the C++ header using any of the available methods for JSON. And then opening the HTML file and dragging and dropping the `.json` into the dedicated area. This method has the fastest loading speed, as then the browser can directly read in the file and parse it with a JSON parser instead of using a more generic (and slower) parser. |
| 42 | + |
| 43 | +After loading the data either way, you can now select on the left side any loaded in data structure for viewing. You can select them and then get a visualization of them in the center of the screen. |
| 44 | +On the top bar you have multiple utilities which allow you to toggle the behavior of the visualization (should the memory be display linearly / in a grid, should the index be visible or just the pure data, should read / write been shown individually or combined). |
| 45 | +When showing both read and write accesses, the read accesses are on top (blue), write ones on bottom (orange). You are also able to click them to view more information. |
| 46 | + |
| 47 | +But you can also generate a single static file containing one dataset with the same template. This will load (considerably) slower, but is functionally the same, and then you only have a single file. To do this, you can use the `parseDataForJSPage` generator of the C++ header file and passing the base HTML file in as input. |
| 48 | + |
| 49 | + |
| 50 | +If you need to rebuild or make changes to the project, you will have to install the dependencies and then run the described commands. |
| 51 | + |
| 52 | +## Installing the project |
| 53 | + |
| 54 | +For this project you need NodeJS and NPM installed. You can get them from [here](https://nodejs.org/en/). |
| 55 | +The latest (LTS) version should be fine. |
| 56 | + |
| 57 | +Both node and npm need to be on the path. |
| 58 | + |
| 59 | +After that, you should install pnpm, as this is the package manager used in this project. |
| 60 | +[Note: You can also use npm, but then you need to change the commands in the following sections and you won't be able to use the pnpm lockfile] |
| 61 | + |
| 62 | +You can install pnpm with the following command: |
| 63 | + |
| 64 | +```bash |
| 65 | +# Install pnpm |
| 66 | +npm install -g pnpm |
| 67 | +``` |
| 68 | + |
| 69 | +Now that you installed pnpm, you need to install all the dependencies for the project. |
| 70 | + |
| 71 | +You can do that with the following command: |
| 72 | + |
| 73 | +```bash |
| 74 | +# Install all dependencies |
| 75 | +pnpm install |
| 76 | +``` |
| 77 | + |
| 78 | +And you are already done with the installation. You can now modify the project and build it. |
| 79 | + |
| 80 | +## Developing |
| 81 | + |
| 82 | +During Development you can use the following command to start a development server: |
| 83 | + |
| 84 | +```bash |
| 85 | +pnpm dev |
| 86 | +# or start the server and open the app in a new browser tab |
| 87 | +pnpm dev -- --open |
| 88 | +``` |
| 89 | + |
| 90 | +This development server will automatically rebuild the project when you change a file. |
| 91 | +So you can instantly see changes in the browser. |
| 92 | + |
| 93 | +You can see all available commands in the `package.json` file. |
| 94 | + |
| 95 | +## Building |
| 96 | + |
| 97 | +To bundle the entire application into the single HTML template, you can use the following command: |
| 98 | + |
| 99 | +```bash |
| 100 | +pnpm build |
| 101 | +``` |
| 102 | + |
| 103 | +This will currently create a `build` folder with an `index.html` file in it. |
| 104 | + |
| 105 | +## More details about the used packages and their files |
| 106 | + |
| 107 | +All packages used in `package.json` are listed here with a short explanation (in alphabetical order). |
| 108 | + |
| 109 | +All packages are in the `devDependencies` section, as we are bundling everything into a single HTML file, so we do not have runtime dependencies (as those will be bundled into that file). |
| 110 | + |
| 111 | +* `@iconify/icons-ic` |
| 112 | + * Add the `icons-ic` icon set for offline use. A list of all available icons can be found [here](https://icon-sets.iconify.design/ic/). |
| 113 | +* `@iconify/svelte` |
| 114 | + * Add a icon component of the `iconify` library which is usable in Svelte. |
| 115 | +* `@skeletonlabs/skeleton` |
| 116 | + * This is a UI framework which provides some pre-made components for svelte (like the drawer) and additionally dictates the default style, the official docs can be found [here](https://www.skeleton.dev/docs/why) |
| 117 | +* `@sveltejs/vite-plugin-svelte` |
| 118 | + * This allows to integrate Svelte easily into Vite. It is applied inside `vite.config.ts` as the first used plugin. At the same time, it forwards Vite's preprocessor to the Svelte config in `svelte.config.js`. This allows Svelte to have for example style blocks which use the `PostCSS` language or Script blocks which use TypeScript. |
| 119 | +* `@tailwindcss/forms` |
| 120 | + * A plugin for tailwindcss which makes it easier to work with forms. (By resetting the default browser form styles and also making them available as classes for other elements) |
| 121 | +* `@tailwindcss/line-clamp` |
| 122 | + * A utility which allows to clamp text after multiple lines. (By default in CSS you can only clamp a single line) |
| 123 | +* `@tailwindcss/typography` |
| 124 | + * Provides a `prose` class which automatically styles all elements within this container with respect to their tags (like `h1`, `h2`, `span`, ...) as by default the style of those classes is removed. |
| 125 | +* `@tsconfig/svelte` |
| 126 | + * This provides a default `.tsconfig` for Svelte projects and can be inherited for the own `tsconfig`. |
| 127 | +* `@typescript-eslint/eslint-plugin` + `@typescript-eslint/parser` |
| 128 | + * Add ESLint (rule) support to TypeScript code. |
| 129 | +* `autoprefixer` |
| 130 | + * A PostCSS plugin to automatically add necessary browser prefixes to CSS, so that more browsers are supported. |
| 131 | +* `color2k` |
| 132 | + * A compact library for color manipulations. (Interpolate between colors, make them more transparent, and be able to output this as a color for CSS) |
| 133 | +* `esbuild` |
| 134 | + * Used by Vite for minification and transpilation. (Also supports features like tree shaking) |
| 135 | +* `eslint` |
| 136 | + * Static Code analyzer to show code errors (or warnings). ESLint can automatically fix certain errors or guidelines. In this project the configuration is mostly managed by Prettier. |
| 137 | + * The rules for ESLint can be found in `.eslintrc.cjs`. Ignored files for ESLint are in `.eslintignore`. |
| 138 | +* `eslint-config-prettier` |
| 139 | + * Makes ESLint compatible with Prettier. |
| 140 | +* `eslint-plugin-svelte3` |
| 141 | + * Makes ESLint compatible with Svelte. |
| 142 | +* `postcss` |
| 143 | + * Post-processes CSS files to allow plugins to work with them (like `autoprefixer`). For example transforms newer syntax into browser-compatible CSS code and automatically generates polyfills among other things. |
| 144 | +* `prettier` |
| 145 | + * Opinionated Code Formatter (more or less ESLint with pre-made rules). |
| 146 | + * The configuration file for the project can be found in `.prettierrc`, ignored files are defined in `.prettierignore`. |
| 147 | +* `prettier-plugin-svelte` |
| 148 | + * This makes prettier compatible with `.svelte` files. |
| 149 | +* `rollup` |
| 150 | + * Used by Vite for bundling files and Vite plugins extend Rollup's plugin interface. |
| 151 | +* `svelte` |
| 152 | + * The used Component framework for the application. Components made with Svelte end in `.svelte`. An introduction tutorial is available [here](https://svelte.dev/tutorial/basics), the overall docs [here](https://svelte.dev/docs). |
| 153 | + * The configuration can be found at `svelte.config.js`. |
| 154 | +* `svelte-check` |
| 155 | + * A command-line tool (also displayed during build) which checks for type errors, unused CSS and accessibility for `.svelte` files. |
| 156 | +* `tailwindcss` |
| 157 | + * A CSS framework focused on utility classes which speeds up UI development. It provides classes for relatively basic CSS functions allowing you to compose these into blocks you need. Docs are available [here](https://tailwindcss.com/docs/). They might be necessairy to get previews of for example colors or widths and distances. |
| 158 | + * The configuration and loaded plugins can be found at `tailwind.config.cjs`. |
| 159 | +* `tslib` |
| 160 | + * Runtime library for TypeScript which contains commonly used TypeScript helper functions. (Which reduces duplicate code on export) |
| 161 | +* `typescript` |
| 162 | + * Module which allows the usage (and compilation) of TypeScript, which is a superset of JavaScript, which adds static typing to JavaScript which thens allows extensive static analysis of the code. |
| 163 | + * The configuration for the project can be found at `tsconfig.json`. |
| 164 | +* `vite` |
| 165 | + * A frontend build tooling, which allows to have a HMR (Hot Module Replacement) development server, and to then also bundle all necessary files into an exported application. |
| 166 | + * The configuration is in `vite.config.ts` |
| 167 | +* `vite-plugin-singlefile` |
| 168 | + * A vite plugin which allows bundling all outputs files into a single HTML file. (Instead of for example 1 big HTML with 1 CSS and 1 JS file) |
| 169 | + |
| 170 | +## Entrypoint for Development |
| 171 | + |
| 172 | +This section will shortly describe where you can find the individual components of the project and where you would need to change things. |
| 173 | + |
| 174 | +The entry point for the overall app is actually `./index.html` as this gets loaded in by Vite. This file also contains the overall HTML base structure. |
| 175 | +In this file, the entrypoint to the application is loaded by importing `src/main.ts` as a script. |
| 176 | + |
| 177 | +This is the first point of the application where code runs. |
| 178 | +The current code is quite simple, and just's loads in the Svelte component in the `src/App.svelte` file and puts this component into the DOM. |
| 179 | + |
| 180 | +The entirety of the remaining application is then contained within the Svelte components. |
| 181 | + |
| 182 | +`App.svelte` loads in the `src/components/Layout.svelte` component for overall page structure (header, ...). Then all the key data is loaded. For that a JSON object is parsed which is supposed to contain all the memory information. During development example data from `data` is loaded in. At export, it will be just a placeholder string, which needs to be filled in by the C++ application. Alternatively there is a drag n' drop area where users can drag in their files. |
| 183 | + |
| 184 | +Global CSS classes are loaded in `src/components/Layout.svelte`, to define own global CSS `src/app.pcss` can be used. But it is advised to keep CSS contained within the Svelte components. |
| 185 | + |
| 186 | +`src/components` contains all the existing components for the app, for more information about the individual components, just take a look at them and the overall file structure. |
| 187 | + |
| 188 | +`src/lib` contains pure TypeScript files. |
| 189 | +`types.ts` contains the type definitions for the loaded memory data, and also contains utility classes for storing and parsing that data while providing the UI with the necessary aggregated information. |
| 190 | +`stores.ts` contains Svelte stores. These are objects which allow storing state in Svelte which are available and changeable in the entire application. |
0 commit comments