yv01p/Umbraco-CMS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve BUILD.md with new backoffice info

Browse Source
This commit is contained in:
Jacob Overgaard
2024-11-13 16:37:56 +01:00
parent 6b85584c02
commit b4609e0388
1 changed files with 34 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
.github/BUILD.md vendored
View File

@@ -13,17 +13,6 @@ If the answer is yes, please read on. Otherwise, make sure to head on over [to t
↖️ You can jump to any section by using the "table of contents" button ( ![Table of contents icon](img/tableofcontentsicon.svg) ) above.
## Getting Started:
To run umbraco, we first need to initialize the client git submodule:
* Execute `git submodule update --init` to get the files into Umbraco.Web.UI.Client project
* If you are going to work on the Backoffice, you can either go to the Umbraco.Web.UI.Client folder and check out a new branch or set it up in your IDE, which will allow you to commit to each repository simultaneously:
* **Rider**: Preferences -> Version Control -> Directory Mappings -> Click the '+' sign
* If you get a white page delete Umbraco.Cms.StaticAssets\wwwroot\umbraco folder and run `npm ci && npm run build:for:cms` inside Umbraco.Web.UI.Client folder to clear out any leftover files from older versions.
### Latest version
* If you want to get the latest changes from the client repository, run `git submodule update` again which will pull the latest main branch.
## Debugging source locally
Did you read ["Are you sure"](#are-you-sure)?
@@ -32,29 +21,34 @@ Did you read ["Are you sure"](#are-you-sure)?
If you want to run a build without debugging, see [Building from source](#building-from-source) below. This runs the build in the same way it is run on our build servers.
> [!NOTE]
> The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to [disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools)][disable browser caching] to help you to see the changes you're making.
#### Debugging with VS Code
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
* [Visual Studio Code](https://code.visualstudio.com/)
* [dotnet SDK v7+](https://dotnet.microsoft.com/en-us/download)
* [Node.js v14+](https://nodejs.org/en/download/)
* npm v7+ (installed with Node.js)
* [Git command line](https://git-scm.com/download/)
- [Visual Studio Code](https://code.visualstudio.com/)
- [dotnet SDK v9+](https://dotnet.microsoft.com/en-us/download)
- [Node.js v20+](https://nodejs.org/en/download/)
- npm v10+ (installed with Node.js)
- [Git command line](https://git-scm.com/download/)
Open the root folder of the repository in Visual Studio Code.
To build the front end you'll need to open the command pallet (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and run `>Tasks: Run Task` followed by `Client Watch` and then run the `Client Build` task in the same way.
To build the front end you'll need to open the command pallet (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and run `>Tasks: Run Task` followed by `Client Build`.
You can also run the tasks manually on the command line:
```
cd src\Umbraco.Web.UI.Client
npm i
npm run dev
npm run build:for:cms
```
If you just want to build the UI Client to `Umbraco.Web.UI` then instead of running `dev`, you can do: `npm run build`.
If you just want to watch the UI Client to `Umbraco.Web.UI` then instead of running `build:for:cms`, you can do: `npm run dev:mock`. This will launch the Vite dev server on http://localhost:5173 and watch for changes with mocked API responses.
You can also run `npm run dev:server` to run the Vite server against a local Umbraco instance. In this case, you need to have the .NET project running and accept connections from the Vite server. Please see the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
The login screen is a different frontend build, for that one you can run it as follows:
@@ -66,12 +60,6 @@ npm run dev
If you just want to build the Login screen to `Umbraco.Web.UI` then instead of running `dev`, you can do: `npm run build`.
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
You might run into [Gulp quirks](#gulp-quirks).
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to [disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools)][disable browser caching] to help you to see the changes you're making.
To run the C# portion of the project, either hit <kbd>F5</kbd> to begin debugging, or manually using the command line:
```
@@ -86,24 +74,18 @@ When the page eventually loads in your web browser, you can follow the installer
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
* [Visual Studio 2022 v17+ with .NET 7+](https://visualstudio.microsoft.com/vs/) ([the community edition is free](https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=Community&rel=15) for you to use to contribute to Open Source projects)
* [Node.js v14+](https://nodejs.org/en/download/)
* npm v7+ (installed with Node.js)
* [Git command line](https://git-scm.com/download/)
- [Visual Studio 2022 v17+ with .NET 7+](https://visualstudio.microsoft.com/vs/) ([the community edition is free](https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=Community&rel=15) for you to use to contribute to Open Source projects)
- [Node.js v20+](https://nodejs.org/en/download/)
- npm v10+ (installed with Node.js)
- [Git command line](https://git-scm.com/download/)
The easiest way to get started is to open `umbraco.sln` in Visual Studio.
To build the front end, you'll first need to run `cd src\Umbraco.Web.UI.Client && npm install` in the command line (or `cd src\Umbraco.Web.UI.Client; npm install` in PowerShell). Then find the Task Runner Explorer (View → Other Windows → Task Runner Explorer) and run the `build` task under `Gulpfile.js`. You may need to refresh the Task Runner Explorer before the tasks load.
Umbraco is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit <kbd>F5</kbd> to see the result. There are two web projects in the solution, `Umbraco.Web.UI.Client` and `Umbraco.Web.UI.Login`. They each have their own build process and can be run separately. The `Umbraco.Web.UI` project is the main project that hosts the back office and login screen. This is the project you will want to run to see your changes. It will automatically restore and build the client projects when you run it.
If you're working on the backoffice, you may wish to run the `dev` command instead while you're working with it, so changes are copied over to the appropriate directories and you can refresh your browser to view the results of your changes.
If you want to watch the UI Client to `Umbraco.Web.UI` then you can open a terminal in `src/Umbraco.Web.UI.Client` where you can run `npm run dev:mock` manually. This will launch the Vite dev server on http://localhost:5173 and watch for changes with mocked API responses.
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
You might run into [Gulp quirks](#gulp-quirks).
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to [disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools)][disable browser caching] to help you to see the changes you're making.
"The rest" is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit <kbd>F5</kbd> to see the result.
You can also run `npm run dev:server` to run the Vite server against a local Umbraco instance. In this case, you need to have the .NET project running and accept connections from the Vite server. Please see the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
**The initial C# build might take a _really_ long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
@@ -134,8 +116,9 @@ This will add a local nuget feed with the name "MyLocalFeed" and you'll now be a
Once the solution has been used to run a site, one may want to "reset" the solution in order to run a fresh new site again.
The easiest way to do this by deleting the following files and folders:
* src/Umbraco.Web.UI/appsettings.json
* src/Umbraco.Web.UI/umbraco/Data
- src/Umbraco.Web.UI/appsettings.json
- src/Umbraco.Web.UI/umbraco/Data
You only have to remove the connection strings from the appsettings, but removing the data folder ensures that the sqlite database gets deleted too.
@@ -150,8 +133,9 @@ The following command will force remove all untracked files and directories, whe
git clean -xdf .
For git documentation see:
* git [clean](<https://git-scm.com/docs/git-clean>)
* git [reset](<https://git-scm.com/docs/git-reset>)
- git [clean](https://git-scm.com/docs/git-clean)
- git [reset](https://git-scm.com/docs/git-reset)
## Azure DevOps
@@ -165,18 +149,6 @@ The produced artifacts are published in a container that can be downloaded from
Git might have issues dealing with long file paths during build. You may want/need to enable `core.longpaths` support (see [this page](https://github.com/msysgit/msysgit/wiki/Git-cannot-create-a-file-or-directory-with-a-long-path) for details).
### Gulp Quirks
You may need to run the following commands to set up gulp properly:
```
npm cache clean --force
npm ci
npm run build
```
[ contribution guidelines]: CONTRIBUTING.md "Read the guide to contributing for more details on contributing to Umbraco"
[ starter kits ]: https://our.umbraco.com/packages/?category=Starter%20Kits&version=9 "Browse starter kits available for v9 on Our "
[ disable browser caching ]: https://techwiser.com/disable-cache-google-chrome-firefox "Instructions on how to disable browser caching in Chrome and Firefox"