Lg/more from impressions (dfinity#332)

* Doc updates based on feedback from the first impressions blog post * Continue with updates from impressions * Continue with updates from impressions * Remove wallet step to fix step numbering * Remove CanCan reference and add links to Rust CDK * Add package.json samples and fix formatting * Change title for different languages * Change title for different languagesin nav
liling0509 · Feb 19, 2021 · e6eeea0 · e6eeea0
1 parent b608429
commit e6eeea0
Show file tree

Hide file tree

Showing 11 changed files with 144 additions and 43 deletions.
diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
@@ -18,7 +18,7 @@
 //xref:developer-guide:connect-network.adoc[Connect to a network]
 ** xref:developers-guide:customize-projects.adoc[Design apps]
 ** xref:developers-guide:customize-projects.adoc[Manage projects]
-** xref:developers-guide:work-with-languages.adoc[Develop using different backend languages]
+** xref:developers-guide:work-with-languages.adoc[Develop using different languages]
 //*** xref:language-guide:at-a-glance.adoc[Motoko]
 //*** xref:rust-guide:basic-syntax-rules.adoc[Rust]
 //*** xref:developers-guide:basic-syntax-rules.adoc[C and C++]

diff --git a/modules/developers-guide/examples/add-stylesheet-package.json b/modules/developers-guide/examples/add-stylesheet-package.json
@@ -0,0 +1,23 @@
+{
+  "name": "contacts_assets",
+  "version": "0.1.0",
+  "description": "",
+  "keywords": [],
+  "scripts": {
+    "build": "webpack"
+  },
+  "devDependencies": {
+    "@dfinity/agent": "0.6.23",
+    "terser-webpack-plugin": "2.2.2",
+    "webpack": "4.41.3",
+    "webpack-cli": "3.3.10"
+  },
+  "dependencies": {
+    "css-loader": "^5.0.2",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "style-loader": "^2.0.0",
+    "ts-loader": "^8.0.17",
+    "typescript": "^4.1.5"
+  }
+}
diff --git a/modules/developers-guide/examples/custom-frontend-package.json b/modules/developers-guide/examples/custom-frontend-package.json
@@ -0,0 +1,21 @@
+{
+  "name": "custom_greeting_assets",
+  "version": "0.1.0",
+  "description": "",
+  "keywords": [],
+  "scripts": {
+    "build": "webpack"
+  },
+  "devDependencies": {
+    "@dfinity/agent": "0.6.23",
+    "terser-webpack-plugin": "2.2.2",
+    "webpack": "4.41.3",
+    "webpack-cli": "3.3.10"
+  },
+  "dependencies": {
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "ts-loader": "^8.0.17",
+    "typescript": "^4.1.5"
+  }
+}
diff --git a/modules/developers-guide/pages/cli-reference/dfx-envars.adoc b/modules/developers-guide/pages/cli-reference/dfx-envars.adoc
@@ -9,7 +9,7 @@ This section lists the environment variables that are currently supported with e
 
 == DFX_CONFIG_ROOT
 
-Use the `+DFX_CONFIG_ROOT+` environment variable to specify a different location for for storing the `+.cache+` and `+.config+` subdirectories for `+dfx+`.
+Use the `+DFX_CONFIG_ROOT+` environment variable to specify a different location for storing the `+.cache+` and `+.config+` subdirectories for `+dfx+`.
 
 By default, the `+.cache+` and `+.config+` directories are located in the home directory for your development environment. 
 For example, on macOS the default location is in the `+/Users/<YOUR-USER-NAME>+` directory.
@@ -19,6 +19,12 @@ Use the `+DFX_CONFIG_ROOT+` environment variable to specify a different location
 DFX_CONFIG_ROOT=~/ic-root
 ....
 
+== DFX_INSTALLATION_ROOT
+
+Use the `+DFX_INSTALLATION_ROOT+` environment variable to specify a different location for the `+dfx+` binary if you are not using the default location for your operating system.
+
+The `+.cache/dfinity/uninstall.sh+` script uses this environment variable to identify the root directory for your {sdk-short-name} installation. 
+
 == DFX_TELEMETRY_DISABLED
 
 Use the `+DFX_TELEMETRY_DISABLED+` environment variable to opt-out of having data collected about `+dfx+` usage.

diff --git a/modules/developers-guide/pages/tutorials/custom-frontend.adoc b/modules/developers-guide/pages/tutorials/custom-frontend.adoc
@@ -80,6 +80,12 @@ npm install --save react react-dom
 ----
 npm install --save typescript ts-loader
 ----
++
+NOTE: As an alternative to installing these modules, you can edit the default `+package.json+` file to add dependencies for your project.
++
+....
+include::example$custom-frontend-package.json[]
+....
 
 == Modify the default configuration
 

diff --git a/modules/developers-guide/pages/tutorials/my-contacts.adoc b/modules/developers-guide/pages/tutorials/my-contacts.adoc
@@ -77,6 +77,12 @@ npm install --save style-loader css-loader
 ----
 +
 If the `+npm install+` command reports a vulnerability, you might also want to run the `+npm audit fix+` command to attempt to fix the vulnerability reported before continuing.
++
+NOTE: As an alternative to installing these modules, you can edit the default `+package.json+` file to add dependencies for your project.
++
+....
+include::example$add-stylesheet-package.json[]
+....
 
 == Modify the default configuration
 

diff --git a/modules/developers-guide/pages/work-with-languages.adoc b/modules/developers-guide/pages/work-with-languages.adoc
@@ -1,4 +1,4 @@
-= Working with different languages
+= Develop using different languages
 :cpp: C++
 :sdk-short-name: DFINITY Canister SDK
 
@@ -9,14 +9,12 @@ This section provides some high-level guidance for writing programs in different
 == Using Rust
 
 You can create Rust projects to run on the {IC} by using Cargo and compiling your program to use WebAssembly as the target output.
-The CanCan sample project illustrates one way of implementing a Rust-based canister—the `+BigMap+` library—using macros to write functions as query and update calls.
 
 This section provides a summary of the key steps involved in deploying a Rust program as a canister on the {IC}.
 You should note, however, that the steps described here only illustrate one approach. 
 Other implementation approaches are also possible. 
-////
-The Rust CDK provides some shortcuts to make it easier to write functions as query and update calls, but you can develop applications for the {IC} without using the Rust CDK.
-////
+
+Note that the link:https://github.com/dfinity/cdk-rs[Rust canister development kit (Rust CDK)] for provides some shortcuts to make it easier to write functions as query and update calls and includes several link:https://github.com/dfinity/cdk-rs/tree/next/examples[examples] to get you started building Rust-based projects, but you can also develop applications for the {IC} without using the Rust CDK.
 
 === Create a project
 

diff --git a/modules/developers-guide/pages/working-with-canisters.adoc b/modules/developers-guide/pages/working-with-canisters.adoc
@@ -1,4 +1,4 @@
-= Managing canisters
+= Manage canisters
 March 2020 (Alpha)
 ifdef::env-github,env-browser[:outfilesuffix:.adoc]
 :proglang: Motoko
@@ -121,6 +121,28 @@ If you were installing canisters on a remote network, you would include the `+--
 dfx canister install --all
 ----
 
+== Look up a canister identifier
+
+All canisters have unique, network-specific identifiers. 
+You often need to use these identifiers to interact with the canister.
+For example, if you want to access the front-end canister for an application or interact with a service using the Candid web interface, you must specify the appropriate canister identifier.
+
+Because the identifiers are network-specific, the files used to store the information are in different directories.
+For example, identifiers for a canister deployed locally are located in the project's `+.dfx/local/canister_ids.json+` file.
+
+You can look up the canister identifier for any specific canister by running the `+dfx canister id+` command.
+For example, to look up the the canister identifier for the `+lookup+` canister deployed on the local network, you could run the following command:
+
+....
+dfx canister id lookup
+....
+
+To look up the canister identifier for the same canister deployed on the network specified by the `+ic+` alias, you would run the following command:
+
+....
+dfx canister --network=ic id lookup
+....
+
 == Reinstall a canister
 
 During the development cycle, you might want to install, then replace your program as you debug and improve it.

diff --git a/modules/quickstart/pages/local-quickstart.adoc b/modules/quickstart/pages/local-quickstart.adoc
@@ -128,16 +128,10 @@ As a best practice, this step requires you to have **two terminal shells** open,
 To start the network locally:
 
 [arabic]
-. Open a new second terminal window or tab on your local computer and navigate to your project directory.
+. Open a new second terminal window or tab on your local computer.
+. Navigate to the root directory for your project, if necessary.
 +
-For example, you can do either of the following if running Terminal on macOS:
-+
---
-* Click *Shell*, then select *New Tab* to open a new terminal in your current working directory.
-* Click *Shell* and select *New Window*, then run `+cd ~/ic-projects/hello+` in the new terminal if your `+hello+` project is in the `+ic-projects+` working folder.
---
-+
-You should now have **two terminals** open with your **project directory** as your **current working directory**.
+You should now have **two terminals** open with your **project directory** as your **current working directory** in both terminals.
 . Start the {IC} network on your local computer in your second terminal by running the following command:
 +
 [source,bash]

diff --git a/modules/quickstart/pages/network-quickstart.adoc b/modules/quickstart/pages/network-quickstart.adoc
@@ -140,7 +140,7 @@ For example, you should see output similar to the following:
 +
 ....
 {
-  "ic_api_version": "0.11.1"  "impl_version": "2020-10-14"
+  "ic_api_version": "0.14.0"  "impl_hash": "40d5e890ae5c3558fbb4281ec04a5c0d0c1c0104012a33dfc8ecb0445057f405"  "impl_version": "0.1.0"  "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 133, 168, 228, 168, 232, 127, 43, 51, 212, 173, 127, 167, 169, 84, 223, 125, 69, 157, 31, 105, 91, 34, 207, 123, 136, 227, 152, 187, 36, 246, 25, 58, 90, 24, 169, 86, 122, 201, 212, 11, 111, 43, 156, 193, 106, 11, 210, 217, 22, 13, 187, 148, 153, 152, 176, 171, 45, 130, 247, 231, 157, 251, 92, 190, 202, 13, 150, 116, 95, 187, 28, 157, 173, 170, 60, 156, 45, 127, 248, 25, 95, 9, 43, 102, 161, 46, 198, 237, 227, 77, 244, 79, 227, 134, 69, 161]
 }
 ....
 
@@ -168,51 +168,41 @@ dfx deploy --network=ic
 ----
 +
 The `+dfx deploy+` command output displays information about the operations it performs.
++
 For example, this step registers two network-specific identifiers—one for the `+hello+` main program and one for the `+hello_assets+` front-end user interface—and installation information similar to the following:
 +
 ....
 Deploying all canisters.
 Creating canisters...
 Creating canister "hello"...
-"hello" canister created on network "ic" with canister id: "2lolz-fluaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"
+"hello" canister created on network "ic" with canister id: "bj6e2-xqaaa-aaaab-aagja-cai"
 Creating canister "hello_assets"...
-"hello_assets" canister created on network "ic" with canister id: "hupnp-k3uaa-aaaaa-aaaaa-caaaa-aaaaa-aaaaa-q"
+"hello_assets" canister created on network "ic" with canister id: "ro5wz-6qaaa-aaaaa-qagsa-cai"
 Building canisters...
 Building frontend...
 Installing canisters...
-Installing code for canister hello, with canister_id 2lolz-fluaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
-Installing code for canister hello_assets, with canister_id hupnp-k3uaa-aaaaa-aaaaa-caaaa-aaaaa-aaaaa-q
+Installing code for canister hello, with canister_id bj6e2-xqaaa-aaaab-aagja-cai
+Installing code for canister hello_assets, with canister_id ro5wz-6qaaa-aaaaa-qagsa-cai
+Uploading assets to asset canister...
 Deployed canisters.
 ....
-+
-
-NOTE: If you created a project with a different name, keep in mind that your canister names will match your project name instead of `+hello+` and `+hello_assets+`.
-
-////
-. Check that your wallet canister is properly configured and holds a balance of cycles by running a command similar to the following:
-+
-[source,bash]
-----
-dfx canister --network=ic call <WALLET-CANISTER-ID> cycle_balance
-----
-+
-The command returns the cycle balance for the wallet canister identifier you specified.
-For example:
-+
-....
-(99999994564407680)
-....
-////
 . Call the `+hello+` canister and the predefined `+greet+` function by running the following command:
 +
 [source,bash]
 ----
 dfx canister --network=ic call hello greet everyone
 ----
 +
-This example uses the `+dfx canister call+` command to pass "everyone" as an argument to the `+greet+` function.
+Let's take a closer look at this example:
 +
-Remember, however, that if you created a project with a different name, the canister name will match your project name and you'll need to modify the command line to match the name you used instead of `+hello+`.
+-- 
+
+* Using the `+--network=ic+` option indicates that the canister you want to call is deployed on the `+ic+` network. The `+ic+` network alias is an internally-reserved alias for accessing the {IC}.
+* Note that the `+--network=ic+` option must precede the operation subcommand, which, in this case, is the `+dfx canister call+` command.
+* The `+hello+` argument specifies the name of the canister you want to call.
+* The `+greet+` argument specifies the name of the function you want to call in the `+hello+` canister.
+* The text string `+everyone+` is the argument that you want to pass to the `+greet+` function.
+--
 . Verify the command displays the return value of the `+greet+` function.
 +
 For example:

diff --git a/modules/quickstart/pages/newcomers.adoc b/modules/quickstart/pages/newcomers.adoc
@@ -16,6 +16,7 @@ Before you install the {sdk-short-name}, you need to know:
 * How to open and run commands in a terminal
 * How to check for and install packages and dependencies
 * How to create and navigate to new directories
+* How to view and update your PATH on the platform you use
 
 The steps in this section describe how to prepare a basic development environment.
 
@@ -112,4 +113,38 @@ mkdir ic-projects
 cd ic-projects
 ----
 
+[[check-path]]
+== View directories in your PATH
+
+The `+PATH+` environment variable is an important setting that your operating system uses to locate
+the set of directories where executable programs are located. 
+Because every operating system has its own set of directories where it expects to find programs, you need to know how to view and update the PATH environment variable so that you can verify that the {sdk-short-name} command-line executable—`+dfx+`—is in one of the directories listed.
+
+On macOS computers, the default location for the `+dfx+` executable is `+/usr/local/bin+` and this directory is typically included in the default set of paths. 
+Therefore, updating the `+PATH+` variable is usually not necessary for computers running macOS.
+If you are using a Linux distribution, however, you should know how to do the following:
+
+* Verify the location of the `+dfx+` executable.
+* View the set of directories in your current `+PATH+`.
+* Update the `+PATH+` environment variable, if necessary.
+
+On most operating systems, you can run a command similar to the following to view the set of directories in your current `+PATH+`:
+
+....
+export $PATH
+....
+
+To check the location of the `+dfx+` executable after you install the {sdk-short-name}, you might run a command similar to the following:
+
+....
+which dfx
+....
+
+If the `+dfx+` executable is not in one of the directories listed in your current `+$PATH+`, you need to move the executable or update the `+PATH+` setting.
+The specific steps for updating the `+PATH+` depend on your operating system, but, in many cases, you can run a command similar to the following and specifying the appropriate directory, such as `+~/bin+`:
+
+....
+export PATH=<path-to-directory-for-dfx>
+....
+
 Now you're ready to link:local-quickstart{outfilesuffix}#download-and-install[install] the {sdk-short-name} and get coding!