BasicUsage

This is a document to help support the usage of BTools.

It is based on Issue #4 (Development use cases outline) . Updates are possible on request.

---

‌

Creation / Development

Most of this will use be handled by the Paclets context. We load that like:

<<BTools`Paclets`

New Projects

These can by handled by the general purpose AppExecute . The interface is centralized to minimize the amount of memorization necessary.

To make a new paclet project run:

AppExecute["Configure", "NewApp"]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp"

You can change where paclets are made and loaded from with:

AppExecute["SetMainDirectory", dir]

Project Content

This has a few bits to it. We can get basic file names like:

AppExecute["FileNames", "BTools", "*Info.m", Infinity]

(*Out:*)

{"Config/BundleInfo.m","Config/DocInfo.m","Config/LoadInfo.m","Config/UploadInfo.m","PacletInfo.m","Private/Config/LoadInfo.m","Resources/Templates/TutorialSite/BuildInfo.m","Resources/Templates/TutorialSite/DeploymentInfo.m"}

Or we can get package names:

AppExecute["ListPackages", "BTools"]~Take~5

(*Out:*)

{"Developer/AuthDialogs","Developer/EncodedCache","Developer/FunctionInfoExtractor","Developer/SyncTools","External/GitConnection"}

Or stylesheets:

AppExecute["ListStylesheets", "BTools"]

(*Out:*)

{"BTools/CodeNotebook","BTools/CodePackage","BTools/CodePackagePlain","BTools/DocGen","BTools/MarkdownNotebook","BTools/PelicanMarkdown","BTools/SyntaxHighlighting"}

And there's some other stuff cooked in

Create PacletInfo

This is handled with a kinda ugly call pattern for now:

AppExecute["RegenerateConfig", "NewApp", "PacletInfo"]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/PacletInfo.m"

To compound the injury we use a different function to extract info about it:

AppPacletExecute["PacletInfo", "NewApp"]

(*Out:*)

<|"Name"->"NewApp","Version"->"1.0.2","Extensions"-><|"Kernel"-><|"Root"->".","Context"->{"NewApp`"}|>|>,"Location"->"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp"|>

The second function could easily handle the first case too. If you want to add parameters that's easy:

AppExecute["RegenerateConfig", 
  "NewApp", 
  "PacletInfo", 
  "Version"->"6.6.6", 
  "Extensions"-><|
    "PacletServer"-><|"Description"->"wow this is a dumb app"|>
    |>
  ]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/PacletInfo.m"

Git Init

For this we can use the AppGit function that wraps the Git interface in the External subcontext for use with app dev stuff:

AppGit["Init", "NewApp"]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp"

AppExecute["FileNames", "NewApp", "*git*"]

(*Out:*)

{".git",".gitignore"}

You can create a repository for this on GitHub with

AppGit["GitHubConfigure", "NewApp"]

(*Out:*)

"https://github.com/b3m2a1/mathematica-NewApp"

And delete it with

AppGit["GitHubDelete", "NewApp"]

(*Out:*)

---

‌

PacletInfo

Paclet Info Modification

Currently as described in the Create PacletInfo section.

Paclet Info Extractors

No real plans to go beyond what has been presented before

AppPacletExecute["PacletInfo", "BTools"]["Version"]

(*Out:*)

"2.1.12"

Increment Version

Currently done by default when regenerating PacletInfo expression

---

‌

Kernel

Add Package

Currently implemented under the "AddContent" function in AppExecute :

AppExecute["AddContent", "NewApp", 
  AppExecute["ListPackages", "BTools", "DropDirectory"->False][[1]]
  ]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/Packages/AuthDialogs.m"

Generally will be auto-detected, but the path can be specified as desired:

AppExecute["AddContent", "NewApp", 
  "~/Desktop/garbage_collector.nb",
  "Packages"
  ]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/Packages/garbage_collector.nb"

---

‌

FrontEnd

Add Stylesheet

Currently implemented under the "AddContent" function in AppExecute :

AppExecute["AddContent", "NewApp", 
  AppExecute["ListStylesheets", "BTools", "DropDirectory"->False][[1]]
  ]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/FrontEnd/StyleSheets/NewApp/CodeNotebook.nb"

Generally will be auto-detected, but the path can be specified as desired:

AppExecute["AddContent", "NewApp", 
  AppExecute["ListStylesheets", "BTools", "DropDirectory"->False][[1]],
  "Palettes"
  ]

(*Out:*)

"/private/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/NewApp/FrontEnd/Palettes/CodeNotebook.nb"

---

‌

Documentation

New Doc Page

Currently implemented the DocGen interface. The AppDocGen wrapper on this needs some work to account for recent changes in DocGen modularization.

DocGen["SymbolPage", DocGen]

(*Out:*)

DocGen["Guide", "BTools`Paclets`"]

(*Out:*)

Pages can be saved to a directory by passing Method options:

DocGen["SymbolPage", DocGen, 
  Method->
    {
      "Save", 
      Directory->AppExecute["Path", "NewApp", "Documentation", "English"]
      }
  ]

AppExecute["ListContent", "NewApp", "SymbolPages"]

(*Out:*)

{"DocGen"}

See more here .

Build Documentation

Multi-paclet docs can be built like:

DocGen["Paclet", 
  {
    "BTools`Paclets`",
    "BTools`Developer`"
    }
  ]

More info on this and the other options and methods is available if desired.

---

‌

Testing

Create Tests

Currently no support. More knowledge of MUnit required.

Run Tests

Currently no support. More knowledge of MUnit required.

---

‌

Package Functions

A number of package-specific functions are provided to make development smoother without linking against outside packages. Two big ones are:

PackageFilePath

Provides relative linking to from the package root

PackageAddAutocompletions

Conveniently attaches autocompletions to symbols

Also provides is

$PackageName

Which is just the name of the package

---

‌

Releases / Deployment

Git Commit

In the AppGit wrapper:

AppGit["Commit", "BTools"]

(*Out:*)

"[master cc471c0] Committed BTools application @ 2018-05-30_01:29:09\n 39 files changed, 3260 insertions(+), 2309 deletions(-)\n create mode 100644 project/BasicUsage.md\n create mode 100644 project/img/basicusage-4666648522623206664.png\n create mode 100644 project/img/basicusage-550941416480850982.png\n create mode 100644 project/img/basicusage-69428561328746212.png\n create mode 100644 project/img/basicusage-7425717185455079729.png\n create mode 100644 project/img/basicusage-8415866144166657194.png\n create mode 100644 project/img/basicusage-8619797801934996806.png\n create mode 100644 project/img/paclets-2372610212413813325.png\n create mode 100644 project/img/paclets-265881908806275627.png\n create mode 100644 project/img/paclets-3060751501420587715.png\n create mode 100644 project/img/paclets-3944086624101741822.png\n create mode 100644 project/img/paclets-6306276067128488378.png\n create mode 100644 project/img/paclets-6456334289508492125.png\n create mode 100644 project/img/paclets-8031869743256385252.png\n create mode 100644 project/img/paclets-8090201827297721276.png\n create mode 100644 project/img/paclets-8350260503414164841.png\n create mode 100644 project/img/paclets-8783817164103644286.png"

Git Tag

<<BTools`External`

In the Git interface but not the AppGit wrapper:

Git["Tag", "Options"]

(*Out:*)

{"Annotate"->Automatic,"Sign"->Automatic,"LocalUser"->Automatic,"Force"->Automatic,"Delete"->Automatic,"Verify"->Automatic,"List"->Automatic,"Sort"->Automatic,"IgnoreCase"->Automatic,"Column"->Automatic,"Contains"->Automatic,"NoContains"->Automatic,"Merged"->Automatic,"NoMerged"->Automatic,"PointsAt"->Automatic,"Message"->Automatic,"File"->Automatic,"Cleanup"->Automatic,"CreateReflog"->Automatic}

GitHub Releases

<<BTools`External`

Supported by the GitHub interface in rudimentary fashion, but without any convenient wrapping:

GitHub["CreateRelease", ...]

GitHub["EditRelease", ...]

GitHub["UploadReleaseAsset", ...]

GitHub["EditReleaseAsset", ...]