Jypeli/Visual Studio-kehitystyökalut macOS-käyttöjärjestelmälle

Näillä ohjeilla asennetaan Jypeli-kehitystyökalut (Visual Studio ja Jypeli) macOS-käyttöjärjestelmään.

Tarvitset näitä sivuja VAIN jos et jostakin syystä halua käyttää Rider-työkalua!

(Windows- ja Linux-käyttöjärjestelmille on omat ohjeensa.)

1. Asennuksen vaiheet

1. Aktivoi tai luo itsellesi Microsoft-tili
2. Asenna Visual Studio for Mac 2022
3. Asenna Jypeli

2. Microsoft-tili

Visual Studion käyttöön tarvitaan Microsoft-tili. Voit (a) käyttää yliopiston käyttäjätunnustasi aktivoimalla siihen Office 365 -palvelut, tai (b) käyttää henkilökohtaista tiliä.

Jos haluat käyttää sinun henkilökohtaista Microsoft-tiliä, voit ohittaa tämän kohdan.

Aktivoi yliopiston käyttäjätunnuksesi Office 365 -pilvipalvelut.

1. Siirry osoitteeseen https://account.jyu.fi
2. Klikkaa Palvelut.
3. Laita ruksi kohtaan Microsoft Office 365 -pilvipalvelut. Hyväksy mahdolliset käyttöehdot.

Aktivoituasi nämä palvelut yliopiston käyttäjätunnuksesi lyhyessä muodossa tunnus@jyu.fi toimii Microsoft-tilinä. Huomaa, että tässä ''tunnus'' on sinun käyttäjätunnuksesi, ei etunimi.sukunimi-muotoinen sähköpostiosoite. Student-osaa ei myöskää tule kirjoittaa.

3. Visual Studio for Mac

Lataa ja asenna Visual Studio for Mac 2022: https://visualstudio.microsoft.com/vs/mac/ Asennusvaiheessa varmista että .NET on valittuna.

Asennuksen lopuksi asentaja saattaa kysyä CLI-toolsin asentamisesta, asenna ne. Eli kysyy "Install Command Line Tools for Xcode" ja siihen Install Tools.

4. Jypelin asentaminen

4.1 Asentaminen VS 2022:een

Avaa Pääte (engl. Terminal, löytyy Launchpadista "Other"-kansiosta) ja syötä seuraava komento.

dotnet new --install Jypeli.Templates

Näet Pääte-ikkunaan tulostuvasta tekstistä onnistuiko asennus.

Komentorivin käyttöä harjoitellaan enemmän kurssin aikana.

4.2 Kokeile toimiiko

Avaa Visual Studio ja valitse auenneesta pääikkunasta New. Aukeavassa ikkunassa on erilaisia projektimalleja ja alimpana Other > Custom otsikoiden alta löytyy äsken asennetut projektimallit. Valitse jokin projekti, tässä esimerkissä Tasohyppelypeli.

Anna projektille jokin nimi ja tallennuspaikka, jonka jälkeen valitse Create.

Sinulle aukeaa melko tyhjä näkymä. Ikkunan vasemmassa reunassa olevasta Solution Explorerista klikkaa projektisi nimen vieressä olevaa nuolta ja aukeavasta puurakenteesta ProjektisiNimi.cs-tiedostoa. Ohjelman koodia aukeaa näytölle. Tämän jälkeen kokeile ajaa ohjelma vasemmassa yläkulmassa olevasta nuolesta.

Pelin pitäisi aueta näytölle, sitten vain koodaamaan :)

4.3 Jypelin version vaihtaminen

Luotu projekti käyttää oletuksena aina uusinta saatavilla olevaa Jypelin versiota. Jos haluat vaihtaa käytössä olevaa versiota vanhempaan, se onnistuu seuraavalla tavalla:

• Klikkaa projektisi Solution Explorerista Dependencies-valikkoa hiiren oikealla
• Valitse Manage NuGet Packages

• Aukeavasta ikkunasta valitse Updates-välilehti
• Alas aukeavasta valikosta näet käytössä olevan Jypelin version, sekä uusimman saatavilla olevan
• Oikeassa reunassa olevasta näkymästä voit päivittää Jypelin uusimpaan versioon, tai voit Version valikon kautta vaihtaa ladattavan version johonkin muuhun.
• Klikkaa Update Package

5. Konsoliprojektin tekeminen

Voit lisätä konsoliprojektin olemassa olevaan JyPeli-projektiin tai sitten voit luoda sitä varten uuden Solutionin:

1. File/New solution
2. Ota Other/Custom/ConsoleMain
3. Anna hyvät nimet

6. Komentoriviprojektien ajaminen

6.1 Ajettavan projektin valitseminen

Jos sinulla on samassa Solutionissa useita projekteja, niin muista vaihtaa tarvittava ajettavaksi projektiksi.

6.2 Erillisessä komentorivi-ikkunassa avaaminen

Komentoriviprojekti ajetaan oletusarvoisesti Visual Studion sisäisessä näyttöikkunassa. Projektit voidaan ajaa myös ulkoisessa komentorivi-ikkunassa, mitä tarvitaan erityisesti silloin, kun ohjelma pyytää käyttäjän syötettä:

• Ota Visual Studioon integroitu terminal pois käytöstä, Yläpalkista Visual Studio ja preferences -> Other -> terminal -> "Enable integrated terminal" pois.
• Klikkaa projektin nimeä hiiren oikealla (Trackpadilla/kosketushiirellä kahdella sormella).
• Valitse Options--> Run --> Default.
• Ruksi kohdat: Run on External Console ja Pause console output --> OK.
• Nyt konsoliohjelman ajoa varten käynnistyy aina uusi ikkuna.
• Huomaa, että tämä asetus kannattaa ottaa pois Jypeli-ohjelmia ajettaessa.

7. Microsoft-tilille kirjautuminen

(Olethan tehnyt kohdan 2. Microsoft tili?)

Kirjaudu Microsoft-tilillesi valitsemalla yläpalkista Visual Studio -> Sign in.

8. Sisällön tuominen projektiin (content)

• Kuvat ja äänet lisätään peliprojektin Content-kansioon, joka näkyy editorin tiedostolistauksessa.
  • Kansiosta oikealla napilla -> Add -> Add Files
  • Valitse tiedosto(t) jotka haluat lisätä
  • Rasti "Override default build action" ja valitse listasta "Content"
  • Paina lopuksi Add-painiketta.
  • Klikkaa vielä Monodevelopin tiedostolistauksessa lisäämääsi tiedostoa hiiren oikealla ja valitse Quick Properties > Copy to Output Directory
• Tuettuja tiedostomuotoja tällä hetkellä:
  • Kuvat: png, jpg
  • Äänet: wav (huom EI mp3)
  • Teksti: txt

9. Huomioita

• Jos Jypeli ei lähde pelittämään Mac:lla, asenna Xcode kohdan 10 ohjeiden mukaisesti.
• Jos Macilla käännösvirheeksi tulee "Object reference not set to an instance of an object", syynä voi olla xcoden vanha versio tai viallinen asennus. Kokeile asentaa uusin versio (uudelleen).
• Jos projektimalleja ei näy vielä asennuksen jälkeen, kokeile käynnistää Visual Studio uudelleen.

10. Asetuksia jotka kannattaa tehdä

• Visual Studio/Preferences/Source Code/Code Formatting/C# source code
• sieltä C# Format ja Policy-kohdasta Microsoft Visual Studio`
• Sitten voi vielä Edit painikkeesta muutella yksityiskohtia mielensä mukaan
• Blank lines -kohdan "Between other member declarations" on 2. Tämä täyttää harjoitustyön vaatimuksen "Aliohjelmien loppusulun } 2 tyhjää riviä".
• Blank lines -kohdan "Between type declarations" on 2. Luokkien väliin tulee tällöin myös 2 riviä.
• New Lines -kohdan "Place embedded statements on new line" on "Allow both". Tällöin yhden rivin if- ja for-lauseet ovat mahdollisia, mutta se ei pakota kuitenkaan tähän käytäntöön.
• White space -kohdassa ruksin seuraavia "within parenthesis":ejä: "Declarations", "Statements -> 'if'"

11. ComTest

• lue ComTest yleisesti
• ComTest ja VS for Mac

12. Tunnettuja ongelmia ja niiden ratkaisuja

12.1 Not authorized to send Apple events to terminal

Käyttäjärjestelmän vaatimukset ovat tiukentuneet ja ohjelmien välistä kommunikaatiota on sallittava itse. Katso ohjeet esim Stack Overflow ja tulla sivulla on kuva kun etsii sanaa solution. Pitää sallia oikeus Terminalin ja Visual Studion välille.

12.2 Error: NuGet packages need to be restored before building.

Jos tulee virhe:

Error: NuGet packages need to be restored before building. NuGet
MSBuild targets are missing and are needed for building. The NuGet
MSBuild targets are generated when the NuGet packages are restored.

niin tähän saattaa auttaa kun menee projektin päälle ja ottaa siitä hiiren oikealla Unload ja sen jälkeen Reload.

12.3 Unable to read the NuGet.Config file

Jos Visual Studion uudelleen käynnistäminen ei auta, tähän voi kokeilla näitä ohjeita
https://github.com/xamarin/get-started/issues/19

13. Visual Studio for Mac asennuksen poistaminen jos ei poistu normaaleilla keinoilla

13.1 Jypelin poistaminen ja uudelleen asentaminen

Jos on kyse siitä, että uusi Jypelin versio ei asennu, voi ensin kokeilla seuraavaa:

1. Poista Jypeli extension asennus (Visual Studio Community/Extensions...)

2. IDE extensions -> Jypeli projektimallit ja Uninstall

3. Sammuta VS

4. Katso käynnistyykö uudelleen kiltisti.

5. Jos käynistyy, asenna Jyeplin uusi versio aikaisemmilla ohjeilla

6. Jos ei käynnisty, vaan valittaa että asennus on olemassa mutta ei voi käyttää, niin silloin

7. Sammuta VS

8. Kirjoita komentoriviltä:

    cd ~/Library/Application\ Support/VisualStudio/8.0/LocalInstall/Addins/
    cd Jypeli [ja paina tab jotta täydentyy oikeaksi, katso että tulee Jypeli-hakemisto]
    rm -R *
    # katso että kaikki poistuu, jos ei poistu, poistele yksitellen
    cd ..
    rmdir Jypeli [ja paina tab jotta täydentyy]

9. Nyt käynnistä VS ja asenna Jypelin uusin versio

Olemassa oleviin projekteihin ei versio muutu tällä tavalla vaan jos johonkin projektiin tarvitse uuden Jypelin, joudut tekemään projektin uudelleen (muista että voit kopioida sinne olemassa olevia tiedostoja).

13.2 Visual Studion poistaminen ja uudelleen asentaminen

• mene komentorivillä johonkin sopivaan hakemistoon ja anna komennot

    wget https://raw.githubusercontent.com/MicrosoftDocs/visualstudio-docs/master/mac/resources/uninstall-vsmac.sh
    chmod 777 unin*
    ./uninstall-vsmac.sh

• lisätieto Microsoftin sivuilla

• joskus on tarpeen myös poistaa Mono ja asentaa se uudelleen, ohjeet löytyy Microsoftin sivuilta ylläolevasta linkistä

14. Xcode (asennus vaaditaan mikäli Jypeli ei toimi)

Aluksi MacOS:iin asenna Xcode, joka löytyy Applen App Storesta. Jos Xcode on jo asennettu, katso että siitä on asennettu viimeisin versio.

HUOM. Muista käynnistää XCode vähintään kerran, jotta tarvittavat työkalut asentuvat.

Yrityskoneille: Jos tietokoneessasi on käytössä päivitysten hallinta (Managed software update), asenna Xcode sitä kautta (Optional software...).

Xcoden asennuspaketti on melkein 8 gigatavua, joten paketti kannattaa laittaa latautumaan hyvissä ajoin ennen kurssin alkua.

Xcoden asennuksen jälkeen asenna vielä Xcode Command Line Tools kirjoittamalla komentoriville (eli suomenkielisessä Macissa Pääte-ohjelmaan)

xcode-select --install