Merge pull request #67 from entrylabs/issue/6281

Issue/6281

source/guide/basic/2023-05-25-common_problem.md

@@ -0,0 +1,61 @@
+---
+layout: page
+title: 자주 발생하는 에러
+type: guide
+category: 'Basic'
+order: 4
+---
+
+## Window에서 개발세팅 중 에러
+**Q. npm, yarn과 같은 명령어가 사용이 안되요.**
+
+A1. window에서는 해당 명령어들을 사용하기 위해서는 환경변수를 추가해 주어야 합니다. 
+윈도우 설치 프로그램으로 설치했을 경우 자동으로 추가해 주지만, 다른 방법으로 설치했을 경우 사용자가 직접 추가해 주어야 하는 경우도 있습니다.
+각 개발도구를 설치한 뒤에는 반드시 버전체크 명령어를 사용해서 정상적으로 설치되었는지 확인하시는 것을 추천드립니다.
+
+A2. 경우에 따라서, 사용하고 있는 쉘(powershell, git bash 등)을 새로고침 해줘야 하는 경우가 있습니다. 이 경우 창을 닫은 후 새 쉘 창을 열어 확인해 줍니다.
+
+**Q.window build tools가 제대로 설치되지 않아요**
+
+A. node-gyp를 설치하는 과정에서 window build tools 관련으로 오류가 날 수 있습니다. 상당히 오류가 잦은 부분이므로 몇가지 내용을 공유드립니다.
+
+1. window에서 설치시 가급적 마이크로소프트 공식 페이지에서 visual studio installer로 설치하는 것을 추천드립니다. visual studio community 다운받기를 하시면 설치할 수 있습니다
+
+2. 버전은 가급적 2015, 2017중 하나를 추천드립니다. 현재 엔트리팀에서 사용중인 버전으로 이외 버전은 아직 확인되지 않았습니다.
+
+3. pc에 여러 버전의 window build tools(혹은 visual studio)가 설치되어 있다면, npm config set 명령어로 'msvs_version'을 '2017(혹은2015)'로 세팅해서 원하는 버전을 선택할 수 있습니다.
+설치된 버전이 1개 뿐이라면 자동으로 해당 버전을 찾기 때문에, 필요한 상황이 아니라면 사용하지 마시기 바랍니다.
+
+4. 설치된 window build tools 버전에 따라 요구하는 python 버전이 다를 수도 있습니다. 유의하시기 바랍니다.
+
+
+
+## entry-hw에서 에러
+**Q. yarn serve를 했는데 너무 오래 걸려요.**
+
+A. pc성능에 따라 10분 이상 걸릴 수도 있습니다. 에러가 발생하지 않았다면 정상적인 상황입니다.
+
+**Q. 정상적으로 켜졌는데 모듈이 아무것도 나타나지 않고 흰 화면만 보여요.**
+
+A. electron-rebuild의 빌드가 제대로 되지 않거나 잔여 캐시가 남아서 발생한 문제입니다. 프로젝트의 node_modules를 삭제하시고 'yarn', 'yarn setting'(혹은 'npm i', 'npm run setting') 순으로 재설치해주시기 바랍니다.
+
+## entryjs에서 에러(블록개발)
+**Q. 블럭을 추가했는데 나타나지 않아요.**
+
+A. 블럭이 나타나지 않은 원인에는 여러가지가 있습니다. 크롬 개발자 도구(f12)의 콘솔창에서 아래의 방법들을 순차적으로 테스트해보시기 바랍니다.
+
+1. Entry.모듈명(ex. Entry.Arduino)를 입력해서 존재하는지 확인합니다. 만약 없다면 entryjs에 Entry객체 하위에 모듈이 정상적으로 추가되지 않은 상태입니다.
+
+2. Entry.HARDWARE_LIST['하드웨어 id'] (ex. Entry.HARDWARE_LIST['52.1'])를 입력해서 확인합니다. 만약 없다면 entryjs 모듈에 입력한 id가 정상적이지 않을 확률이 높습니다.
+
+3. Entry.block.하드웨어블록명 (ex. Entry.block.ardublock_analog_list) 이 있는지 확인합니다. 만약 없다면 블록이 정상적으로 추가되지 않은 상태입니다. blockMenuBlocks에 블록을 추가하였는지 확인 바랍니다.
+
+4. 1~3까지 모두 확인되지만 나타나지 않을경우 각 블록의 isNotFor가 모듈.name이름과 동일한지 확인하시기 바랍니다.
+
+**Q. 블럭이 나타나지만 텅빈 블록으로 보여요.**
+
+A. 블럭의 다국어가 정상적으로 추가되지 않은 상황입니다. setLanguage에 블록이름과 동일한 프로퍼티를 추가하고 다국어를 추가해주시기 바랍니다.
+
+
+## 기타 유의사항
+A. 명령어를 정상적으로 입력해도 문제가 발생한다면 사용하는 쉘의 관리자 권한 문제일 수 있습니다. sudo 명령어를 사용하거나 window환경이라면 관리자 권한으로 powershell을 실행시켜 주시기 바랍니다.

source/guide/basic/setting_environment.md

@@ -6,29 +6,41 @@ category: 'Basic'
 order: 1
 ---
 
-## Git 설치
+> NOTICE! 개발 중 문제가 발생하면 [자주 발생하는 오류](/guide/basic/2023-05-25-common_problem.html) 페이지를 참고해 주시기 바랍니다.
 
-> 연관 페이지 : [Git 사용 방법](/guide/etc/2016-05-03-git_fork.html)
+### Git 설치 및 GitHub 회원 가입
 
-엔트리의 오픈소스 프로젝트는 Git을 사용하여 관리합니다.
-Git을 사용하여 코드를 기록하고 반영하므로 반드시 Git을 설치해야 합니다.
+#### Git 설치
+
+> 연관 페이지: [Git 사용 방법](/guide/etc/2016-05-03-git_fork.html)
+
+엔트리의 오픈소스 프로젝트는 Git을 사용하여 관리합니다. Git을 사용하여 코드를 기록하고 오픈소스에 반영하므로 반드시 Git을 설치해야 합니다.
+
+* macOS, Windows 사용자는 [Git - Downloads](https://git-scm.com/downloads)에서 Git 설치 파일을 다운로드하여 실행합니다.
+* Linux 사용자는 [Git - Git 설치](https://git-scm.com/book/ko/v2/%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0-Git-%EC%84%A4%EC%B9%98)를 참고하여 Git을 설치합니다.
 
-- macOS, Windows 사용자는 [Git - Downloads](https://git-scm.com/downloads)에서 Git 설치 파일을 다운로드하여 실행합니다.
-- Linux 사용자는 [Git - Git 설치](https://git-scm.com/book/ko/v2/%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0-Git-%EC%84%A4%EC%B9%98)를 참고하여 Git을 설치합니다.
 
 ---
+#### GitHub 회원 가입
 
-Git 사용이 익숙치 않다면, Git GUI 도구를 사용하는 것도 좋습니다. (선택사항)  
-아래의 도구를 사용하여 좀 더 쉽게 Git 작업을 하실 수 있습니다.
+[GitHub](https://github.com/)은 Git을 사용해 관리할 수 있는 원격 저장소입니다.
+엔트리 프로젝트 또한 GitHub에 저장소가 있습니다.
+다음과 같은 정보를 입력하여 쉽게 GitHub에 회원 가입할 수 있습니다.
 
-> [Github Desktop](https://desktop.github.com/)
-> [SourceTree](https://www.sourcetreeapp.com/)
+![tutorial01](/images/tutorial/tutorial01.png)
 
-## NodeJS 설치
+### Node.js, Node-gyp 개발 환경 설정
 
-엔트리 프로젝트를 개발하기 위해 기본적으로 [Node.js](https://nodejs.org/en/)가 설치되어 있어야 합니다.
 
-Node.js와 함께 설치되는 라이브러리 관리 도구인 npm을 사용하면 엔트리 구동에 필요한 라이브러리를 설치할 수 있습니다.
+---
+#### Node.js 설치
+
+Node.js를 설치하려면 [Node.js](https://nodejs.org/ko/)에서 설치 파일을 다운로드하여 실행합니다.
+
+> 현재 엔트리 개발팀은 16.19.0 버전을 사용 중입니다(2022.05.25 기준). 최소 14이상의 버전 사용을 추천드립니다.
+
+Node.js를 설치하면 npm이 함께 설치됩니다.
+npm을 이용하여 라이브러리를 설치하고 관리할 수 있습니다.
 
 설치가 완료되면 명령 프롬프트 창에서 다음 명령어를 입력해 정상적으로 설치되었는지 확인합니다.
 
@@ -38,22 +50,146 @@ node --version
 ```
 
 정상적으로 설치되었다면 다음과 같은 결과가 출력됩니다. 버전은 다를 수 있습니다.
+윈도우 OS에서 Node.js를 설치했지만 node 명령어 사용이 되지 않는다면 환경변수를 확인해 주시기 바랍니다.
 
 ![tutorial03](/images/tutorial/tutorial03.png)
 
-## SerialPort 라이브러리 빌드 환경 설치
+
+---
+#### Yarn 설치
+
+엔트리 팀은 패키지 매니저로 yarn 을 사용합니다. 그러므로 yarn 을 통해 의존성 관리를 하는 것을 추천드립니다.  
+**yarn 설치가 필수사항은 아니지만, 패키지의 세부버전들이 yarn.lock에 맞추어져 있습니다. npm을 그대로 사용하실 경우 package-lock.json을 제거하시고 사용하시는 것을 추천드립니다.**
+
+yarn 을 설치한 경우, `npm install` 및 `npm run` 명령어는 `yarn` 으로 대체됩니다.  
+(`npm install -> yarn`, `npm run start -> yarn start`)
+
+```bash
+npm install --global yarn
+```
+
+
+---
+#### Node-gyp 설치
 
 엔트리 하드웨어는 시리얼포트 통신을 위해 [node-serialport](https://github.com/node-serialport/node-serialport) 라이브러리를 사용합니다.
 해당 라이브러리를 사용하기 위해서는 C++, python 빌드 환경과 [node-gyp](https://github.com/nodejs/node-gyp) 라이브러리가 필요합니다.  
-빌드에 대한 자세한 사항은 [node-gyp#installation](https://github.com/nodejs/node-gyp#installation) 을 참고해 주세요.
+빌드에 대한 자세한 사항은 [node-gyp ReadMe](https://github.com/nodejs/node-gyp#installation)와 [자주 발생하는 에러](/guide/basic/2023-05-25-common_problem.html) 을 참고해 주세요.
+
+**윈도우의 경우**는 아래 방법중 1가지로 window build tools를 설치해 주세요. 엔트리팀은 2017버전(15.9.50)을 사용중입니다.
+- visual studio installer를 사용해서 visual studio와 함께 설치 [설치](https://visualstudio.microsoft.com/ko/vs/older-downloads/)**(추천)**
+- chocolatey를 사용해서 [설치](https://community.chocolatey.org/packages/visualstudio2017buildtools)
+- ~~npm을 사용해서 설치~~ (2023.05.25일 기준으로, npm에 등록된 window build tools 이미지에 문제가 있어 정상 동작하지 않습니다.)
 
-C++ 빌드 라이브러리인 node-gyp 을 설치해주세요.
+그 다음 빌드 라이브러리인 node-gyp 을 설치해주세요.
 ```bash
+yarn global add node-gyp
+//or
 npm install --global node-gyp
 ```
 
-**윈도우의 경우**는 아래의 명령을 통해 파이썬, 윈도우 C++ 관련 툴을 설치해주세요. (관리자 모드 프롬프트에서 입력하세요)
+
+### 엔트리 프로젝트 설치
+
+
+---
+#### 원격 저장소의 데이터를 자신의 원격 저장소에 복사
+
+엔트리 하드웨어 개발에는 다음과 같은 엔트리 프로젝트가 필요합니다.
+
+* [Entry Js](https://github.com/entrylabs/entryjs): 엔트리 워크스페이스와 블록을 개발할 수 있는 라이브러리
+* [Entry Hardware](https://github.com/entrylabs/entry-hw): 엔트리에 아두이노 등 여러 하드웨어를 연결할 수 있도록 도와주는 프로그램
+
+엔트리 하드웨어 개발은 두 개의 프로젝트를 자신의 원격 저장소에 그대로 복사(fork)하여 작업한 후 작업 내역을 합병 요청하는 방식으로 이루어집니다.
+
+두 저장소에 접속한 후 오른쪽 위의 **Fork**를 클릭하여 자신의 원격 저장소로 복사합니다.
+
+![tutorial04](/images/tutorial/tutorial04.png)
+
+
+---
+#### 자신의 원격 저장소 데이터를 자신의 컴퓨터로 복사
+
+다음 명령어를 실행하여 자신의 원격 저장소 데이터를 자신의 컴퓨터로 복사(clone)합니다. 이 명령은 명령 프롬프트 또는 Git Bash에서 실행할 수 있습니다.
+
+```bash
+git clone https://github.com/[사용자명]/entry-hw.git
+git clone https://github.com/[사용자명]/entryjs.git
+```
+
+
+---
+#### 브랜치 변경
+
+하드웨어 블록을 개발하는 경우 **`develop-hw`**라는 브랜치를 사용해야 합니다.  
+develop-hw 브랜치는 하드웨어 관련 PR 이 모여서, 배포전에 develop 에 merge 되는 용도로 사용 중입니다.  
+(**develop 브랜치는 엔트리 개발팀에서 이슈 처리를 하는 브랜치 입니다.**) 
+
+> Git은 작업 내역을 분할/관리하기 위해 브랜치라는 개념을 사용합니다.
+> 자세한 설명은 [Git - 브랜치란 무엇인가?](https://git-scm.com/book/ko/v1/Git-%EB%B8%8C%EB%9E%9C%EC%B9%98-%EB%B8%8C%EB%9E%9C%EC%B9%98%EB%9E%80-%EB%AC%B4%EC%97%87%EC%9D%B8%EA%B0%80%3F)를 참고하세요.
+
+각 프로젝트의 디렉토리에서 다음 명령어를 실행하여 develop-hw 브랜치를 사용하게 설정합니다.
+
+```bash
+git checkout develop-hw
+```
+
+브랜치를 변경하면 다음과 같은 결과가 출력됩니다.
+
+![tutorial15](/images/tutorial/tutorial15.png)
+
+> 결론적으로는,  
+> entryjs, entry-hw 모두 develop-hw 브랜치에서 작업하시면 됩니다.
+
+---
+#### 의존성 라이브러리 설치하기
+
+엔트리 프로젝트를 실행하려면 추가 라이브러리가 필요합니다. npm을 이용하여 필요한 라이브러리를 설치할 수 있습니다.
+
+> entryjs 디렉터리에서 다음 명령어를 실행합니다.
+
+```bash
+yarn
+//or
+npm install
+```
+
+> entry-hw 디렉터리에서 다음 명령어를 실행합니다.
+
+```bash
+yarn
+yarn setting
+//or
+npm install
+npm run setting
+```
+
+각 명령어를 실행하면 다음과 같은 화면이 출력됩니다.
+
+![tutorial16](/images/tutorial/tutorial16.png)
+
+---
+
+#### 실행해서 정상 설치 확인하기
+
+마지막으로 각 프로젝트를 실행해서 정상적으로 설치 되었는지 확인합니다.
+
+> entryjs 디렉터리에서 다음 명령어를 실행합니다.
+
+```bash
+yarn serve
+//or
+npm run serve
+```
+
+> entry-hw 디렉터리에서 다음 명령어를 실행합니다.
+
 ```bash
-npm install --global --production windows-build-tools
+yarn start
+// or
+npm run start
 ```
 
+각 명령어를 실행하면 다음과 같은 화면이 출력됩니다.
+![entryjs result](/images/entryjs/serve_result.png)
+![entryhw result](/images/entry-hw/start_result.png)

source/guide/entry-hw/2016-05-01-getting_started.md

@@ -20,6 +20,9 @@ Entry Hardware 는 엔트리에서 개발한 엔트리와 하드웨어를 연동
 
 ## 개발환경 세팅
 
+### NOTICE
+**[개발환경설정](/guide/basic/setting_environment.html)에 사전에 필요한 환경설정이 안내되어 있습니다. 먼저 보시는 것을 추천드립니다.**
+
 ### 프로젝트 포크
 
 엔트리 개발시 엔트리의 원본 프로젝트에 직접 작업은 허용되지 않습니다.  

source/guide/entryjs/2018-03-09-getting_started.md

@@ -10,6 +10,8 @@ order: 1
 하드웨어 업체에서는 하드웨어 블록을 추가하는 용도로 사용됩니다.
 
 ## 개발 환경 세팅
+### NOTICE
+**[개발환경설정](/guide/basic/setting_environment.html)에 사전에 필요한 환경설정이 안내되어 있습니다. 먼저 보시는 것을 추천드립니다.**
 
 ### 프로젝트 포크
 엔트리 개발시 엔트리의 원본 프로젝트에 직접 작업은 허용되지 않습니다.  

source/guide/index.md

@@ -25,16 +25,20 @@ updated: 2021-12-11
 현재 엔트리의 모든 기능을 다루고 있지는 않으며 점차 내용을 추가할 예정입니다.
 
 이 문서는 최신 버전과 다른 내용이 있을 수 있습니다.  
-이상한 점을 발견한 경우 [이슈 리포트](https://github.com/entrylabs/docs/issues) 또는 [엔트리 개발팀](mailto:[email protected])에게 문의 바랍니다.
+이상한 점을 발견한 경우 [이슈 리포트](https://github.com/entrylabs/docs/issues) 또는 [엔트리 고객센터](mailto:[email protected])에 문의 바랍니다.
 
 ## 문서 구성
 
 - 시작하기
-  - [엔트리 하드웨어 개발 튜토리얼](/guide/2018-07-30-tutorial.html): 소프트웨어 개발에 익숙하지 않은 하드웨어 개발자도 쉽게 따라할 수 있도록 간단한 예시를 사용하여 엔트리 하드웨어 개발 과정을 설명합니다.
+  - [엔트리 하드웨어 개발 튜토리얼](/guide/quick_start/2018-07-30-tutorial.html): 소프트웨어 개발에 익숙하지 않은 하드웨어 개발자도 쉽게 따라할 수 있도록 간단한 예시를 사용하여 엔트리 하드웨어 개발 과정을 설명합니다.
+- Basic
+  - [개발 환경 세팅](/guide/basic/setting_environment.html): 각 프로젝트를 설치하기 위해 필요한 개발환경 세팅을 설명합니다. **반드시 읽어보시길 바랍니다.**
+  - [PR 요청하기](/guide/basic/pull_request.html): 개발을 완료한 후 이를 Entry에 반영하는 방법을 설명합니다.
+  - [자주 하는 질문](/guide/basic/2016-07-07-faq.html): 개발 이외에 자주하는 질문에 대한 답변을 정리하였습니다.
+  - [자주 발생하는 오류](/guide/basic/2023-05-25-common_problem.html): 개발중 자주 발생하는 오류를 정리하였습니다.
 - [Entry JS](/guide/entryjs/2018-03-09-getting_started.html): 엔트리 하드웨어 블록을 작성하는 방법을 설명합니다.
 - [Entry Hardware](/guide/entry-hw/2016-05-01-getting_started.html): 엔트리 하드웨어 블록과 하드웨어 간 데이터를 주고받을 수 있게 하는 모듈을 작성하는 방법을 설명합니다.
-- [Entry Offline](/guide/entry-mini/2016-12-12-getting_started.html): Entry Offline을 사용하여 프로그램을 개발하는 방법을 설명합니다.
-- [완료된 개발 코드 Pull Request 하기](/guide/end.html): 개발을 완료한 후 이를 Entry에 반영하는 방법을 설명합니다.
+- [Entry Offline](/guide/entry-offline/2017-12-20-getting_started.html): Entry Offline을 사용하여 프로그램을 개발하는 방법을 설명합니다.
 - 기타
   - [Git 사용 방법](/guide/etc/2016-05-03-git_fork.html): 엔트리 오픈소스 프로젝트 이용에 필요한 Git을 이해하는 데 유용한 참고 문서를 정리했습니다.
-  - [FAQ](/guide/etc/2016-07-07-faq.html): 엔트리 오픈소스 프로젝트 관련 자주 묻는 질문과 답변을 정리했습니다.
+  - [FAQ](/guide/basic/2016-07-07-faq.html): 엔트리 오픈소스 프로젝트 관련 자주 묻는 질문과 답변을 정리했습니다.