2016-04-06 04:20:26 +02:00
# Mapping
PowerShell/PowerShell utilizes `dotnet cli` project model.
Source code for a library (executable) is located under `src/<library-name>` .
I.e. System.Management.Automation.dll sources are located under `src/System.Management.Automation`
2017-03-22 18:17:21 +01:00
In the windows source tree, the files are organized differently.
2016-06-14 02:56:56 +02:00
That's why we use `map.json` files in `src/<library-name>` .
2016-04-06 04:20:26 +02:00
This file is a simple json hashtable that describes mapping between files in source depot and GitHub.
2016-06-14 02:56:56 +02:00
* Keys are relative file paths from `psl-monad` (that has the same layout as admin sd enlistment).
* Values are file paths, relative to the corresponding `map.json` folder.
2016-04-06 04:20:26 +02:00
2016-06-14 02:56:56 +02:00
#### Example
There is an entry
```
"monad/src/engine/COM/ComMethod.cs": "engine/COM/ComMethod.cs",
```
in `.\src\System.Management.Automation\map.json` .
2017-03-22 18:17:21 +01:00
It tells us that file `ComMethod.cs` located at `monad/src/engine/COM/ComMethod.cs` in psl-monad (and sd enlistment) is mapped to `src/System.Management.Automation/engine/COM/ComMethod.cs` in PowerShell/PowerShell.
2016-04-06 04:20:26 +02:00
2016-05-18 22:58:59 +02:00
### build.psm1
2016-04-06 04:20:26 +02:00
2017-03-22 18:17:21 +01:00
Our dev module contains a number of functions that can be used to work with this mapping file.
2016-04-06 04:20:26 +02:00
2016-06-14 02:56:56 +02:00
* `Copy-MappedFiles` -- copies files from psl-monad into PowerShell/PowerShell. Used for "sd -> github" integration.
2016-08-18 19:11:57 +02:00
* `Send-GitDiffToSd` -- applies patch from git to **admin** enlistment with respect to all `map.json` files.
2016-06-14 02:56:56 +02:00
It supports `-WhatIf` switch.
2016-04-06 04:20:26 +02:00
```
2016-06-14 02:56:56 +02:00
> Send-GitDiffToSd -diffArg1 32b90c048aa0c5bc8e67f96a98ea01c728c4a5be~1 -diffArg2 32b90c048aa0c5bc8e67f96a98ea01c728c4a5be -AdminRoot d:\e\ps_dev\admin
2016-04-06 04:20:26 +02:00
> cd d:\e\ps_dev\admin
> sd online ...
> # move files to new change list (i.e. with sdb)
> sd submit -c <n>
```
2016-06-14 02:56:56 +02:00
## Updating `map.json`
If you are bringing new (that are not yet included) files from source-depot, you need to update `map.json` in the corresponding folder to include them.
2016-04-06 04:40:59 +02:00
This way, we can keep track of changes and have ability to integrate changes back to Source Depot.
2016-06-14 02:56:56 +02:00
Use this approach for any files from source-depot (including test files)
2016-04-06 20:37:39 +02:00
2016-06-14 02:56:56 +02:00
## Creating `map.json`
2016-04-06 04:40:59 +02:00
2016-06-14 02:56:56 +02:00
If you are creating new folder for that, create `map.json` with all mapped files in it.
2016-04-06 04:40:59 +02:00
2016-06-14 02:56:56 +02:00
* Make a separate commit with update/creation for `map.json` .
Separate commit will help to manage this change.
2016-04-06 04:40:59 +02:00
```
2016-06-14 02:56:56 +02:00
> mkdir .\src\My.New.Module
> notepad .\src\My.New.Module\map.json
# add mappings into the file
2016-04-06 04:40:59 +02:00
```
2016-06-14 02:56:56 +02:00
* Find current baseline SD change-list in tags:
2016-04-06 20:37:39 +02:00
2016-06-14 02:56:56 +02:00
```
> git tag
2016-06-14 03:46:15 +02:00
SD-692351
2016-06-14 02:56:56 +02:00
SD-693793
SD/688741
SD/692351
SD/693793
SD/695331
SD/700586
SD/704605
SD/706766
2016-06-14 03:46:15 +02:00
SD/709766 < --- the last changelist
2016-06-14 02:56:56 +02:00
v0.1.0
v0.2.0
v0.3.0
v0.4.0
```
* Find corresponding commit in psl-monad and check it out.
```
> Push-Location ..\psl-monad
> git checkout 85e2ecd
> Pop-Location
```
* Use `Copy-MappedFiles` function to copy files on disk.
```
> Copy-MappedFiles -PslMonadRoot ..\psl-monad -Path .\src\My.New.Module
```
* Make a separate commit with mapped files.
Use `--author="PowerShell Team <PowerShellTeam@hotmail.com>"` switch to indicate that it's a collective work.
```
git commit --author="PowerShell Team < PowerShellTeam @ hotmail . com > "
```